Skip to content

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

refactor: start migrate to React for SQL Editor (#20055)

ecmadao326d8b9bbfe9
diff --git a/docs/superpowers/plans/2026-04-20-sql-editor-react-migration-stage-1.md b/docs/superpowers/plans/2026-04-20-sql-editor-react-migration-stage-1.md
new file mode 100644
index 0000000000..a8ac1f67e5
--- /dev/null
+++ b/docs/superpowers/plans/2026-04-20-sql-editor-react-migration-stage-1.md
@@ -0,0 +1,1087 @@
+# SQL Editor React Migration — Stage 1 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Migrate `frontend/src/views/sql-editor/EditorPanel/Welcome/Welcome.vue` (77 lines, 2 buttons gated by permissions) to React, establishing the bottom-up React-island pattern for the SQL Editor with exact UX parity.
+
+**Architecture:** Keep the Vue orchestrator (`SQLEditorLayout`, `SQLEditorPage`, all `provide/inject` contexts, all Pinia stores). Embed React leaves inline inside the Vue tree using the existing `frontend/src/react/ReactPageMount.vue`. The React `Welcome` leaf accesses Pinia stores, the router, and permissions directly; it receives exactly one Vue-context-coupled callback (`onChangeConnection`) as a prop from its Vue parent (`StandardPanel.vue`).
+
+**Tech Stack:** React 18, `@base-ui/react`, Tailwind CSS v4, `class-variance-authority`, `react-i18next`, `vitest`, Vue 3 (parent side), Pinia. Existing hooks/utilities: `useVueState`, `usePermissionCheck`.
+
+**Reference spec:** `docs/superpowers/specs/2026-04-20-sql-editor-react-migration-stage-1-design.md`
+
+**Workflow note:** **Do not auto-commit** — user commits manually. Each task ends with a "Stop for user review" checkpoint. The user will stage and commit at their own cadence.
+
+---
+
+## File Structure
+
+| File | Action | Responsibility |
+|---|---|---|
+| `frontend/src/react/locales/{en-US,zh-CN,es-ES,ja-JP,vi-VN}.json` | Modify | Add two keys: `sql-editor.add-a-new-instance`, `sql-editor.connect-to-a-database`. Strict 1:1 parity enforced by `check-react-i18n.mjs`. |
+| `frontend/src/react/components/BytebaseLogo.tsx` | Create | Shared logo: renders workspace custom logo if present, else fallback SVG. Reads `useWorkspaceV1Store` via `useVueState`. Supports optional `redirect` prop for future callers. |
+| `frontend/src/react/components/BytebaseLogo.test.tsx` | Create | Unit tests for both logo states. |
+| `frontend/src/react/components/sql-editor/WelcomeButton.tsx` | Create | Large square icon-over-label button. Mirrors Vue `Button.vue`. Built on shadcn `Button` with a `cva` variant for 7rem × 7rem shape. |
+| `frontend/src/react/components/sql-editor/WelcomeButton.test.tsx` | Create | Unit tests for icon/label slots and click. |
+| `frontend/src/react/components/sql-editor/Welcome.tsx` | Create | The leaf. Two conditionally-rendered `WelcomeButton`s gated by `usePermissionCheck`. Router push for Add-Instance; `onChangeConnection` prop callback for Connect. |
+| `frontend/src/react/components/sql-editor/Welcome.test.tsx` | Create | Unit tests for permission gating + callback wiring. |
+| `frontend/src/react/mount.ts` | Modify | Register `./components/sql-editor/*.tsx` glob so `ReactPageMount` can load `Welcome`. |
+| `frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue` | Modify | Replace `<Welcome v-else />` with `<ReactPageMount v-else page="Welcome" :on-change-connection="changeConnection" />`; add `showConnectionPanel`, `asidePanelTab` to existing `useSQLEditorContext()` destructure; define `changeConnection`. |
+| `frontend/src/views/sql-editor/EditorPanel/Welcome/` (entire dir) | Delete | `Welcome.vue`, `Button.vue`, `index.ts` — orphaned after the swap. |
+
+---
+
+## Task 1: Add React i18n keys
+
+**Goal:** Ensure `t("sql-editor.add-a-new-instance")` and `t("sql-editor.connect-to-a-database")` resolve in the React i18n resource. `check-react-i18n.mjs` enforces 1:1 parity across all 5 locales — must add to all five.
+
+**Files:**
+- Modify: `frontend/src/react/locales/en-US.json`
+- Modify: `frontend/src/react/locales/zh-CN.json`
+- Modify: `frontend/src/react/locales/es-ES.json`
+- Modify: `frontend/src/react/locales/ja-JP.json`
+- Modify: `frontend/src/react/locales/vi-VN.json`
+
+Reference values (already in Vue locales at `frontend/src/locales/*.json`):
+
+| Locale | `add-a-new-instance` | `connect-to-a-database` |
+|---|---|---|
+| en-US | `Add new instance` | `Connect to database` |
+| zh-CN | (copy from `frontend/src/locales/zh-CN.json`) | (copy from same) |
+| es-ES | `Agregar nueva instancia` | `Conectar a base de datos` |
+| ja-JP | `新しいインスタンスを追加` | (copy from `frontend/src/locales/ja-JP.json`) |
+| vi-VN | (copy from `frontend/src/locales/vi-VN.json`) | (copy from same) |
+
+- [ ] **Step 1: Look up the exact values in the Vue locale files**
+
+Run:
+```bash
+for f in en-US zh-CN es-ES ja-JP vi-VN; do
+ echo "=== $f ==="
+ grep -n "add-a-new-instance\|connect-to-a-database" \
+ "frontend/src/locales/$f.json"
+done
+```
+
+Record the exact strings from each locale. These are the source of truth — do not translate independently.
+
+- [ ] **Step 2: Find the `sql-editor` block in each React locale file**
+
+Each React locale has a `sql-editor` block (en-US.json line 2102). The keys are alphabetically sorted within the block. Example current state in `en-US.json`:
+
+```json
+ "sql-editor": {
+ "access-grants": "Access Grants",
+ "access-type-unmask": "See unmasked sensitive data",
+ "activate-access": "Activate",
+ ...
+ }
+```
+
+- [ ] **Step 3: Add the two keys alphabetically in each locale**
+
+In `frontend/src/react/locales/en-US.json`, inside the `"sql-editor"` object, insert:
+
+```json
+ "access-grants": "Access Grants",
+ "access-type-unmask": "See unmasked sensitive data",
+ "activate-access": "Activate",
+ "activate-confirm": "Are you sure you want to activate this access grant?",
+ "add-a-new-instance": "Add new instance",
+ ...
+ "connect-to-a-database": "Connect to database",
+ ...
+```
+
+Repeat for the other 4 locales using the values from Step 1.
+
+- [ ] **Step 4: Run the sort script to confirm ordering is canonical**
+
+Run:
+```bash
+node frontend/scripts/sort_i18n_keys.mjs
+```
+
+Expected: file is re-sorted in place (no-op if Step 3 was ordered correctly). Inspect the diff — should only touch the 2 new keys.
+
+- [ ] **Step 5: Run the React i18n consistency check**
+
+Run:
+```bash
+node frontend/scripts/check-react-i18n.mjs
+```
+
+Expected: no "missing key" or "consistency" errors for these two keys across the 5 locales. (There will be "unused" warnings for them until Tasks 4/6 land — that is expected for now. If the script fails hard on unused, skip this verification step until after Task 6.)
+
+- [ ] **Step 6: Stop for user review**
+
+Report: "i18n keys added to 5 React locale files. Ready for commit." Wait for user to commit or request changes.
+
+---
+
+## Task 2: Create `BytebaseLogo.tsx` (TDD)
+
+**Goal:** A React-native `BytebaseLogo` that replaces `frontend/src/components/BytebaseLogo.vue`. Welcome uses it without a `redirect` prop, but we build it fully so future React pages (and Stage 9 shell) can reuse.
+
+**Files:**
+- Create: `frontend/src/react/components/BytebaseLogo.tsx`
+- Create: `frontend/src/react/components/BytebaseLogo.test.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `frontend/src/react/components/BytebaseLogo.test.tsx`:
+
+```tsx
+import type { ReactElement } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mocks = vi.hoisted(() => ({
+ useVueState: vi.fn<(getter: () => unknown) => unknown>(),
+}));
+
+vi.mock("@/react/hooks/useVueState", () => ({
+ useVueState: mocks.useVueState,
+}));
+
+vi.mock("@/assets/logo-full.svg", () => ({
+ default: "/assets/logo-full.svg",
+}));
+
+let BytebaseLogo: typeof import("./BytebaseLogo").BytebaseLogo;
+
+const renderIntoContainer = (element: ReactElement) => {
+ const container = document.createElement("div");
+ const root = createRoot(container);
+ return {
+ container,
+ render: () => {
+ act(() => {
+ root.render(element);
+ });
+ },
+ unmount: () =>
+ act(() => {
+ root.unmount();
+ }),
+ };
+};
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ ({ BytebaseLogo } = await import("./BytebaseLogo"));
+});
+
+describe("BytebaseLogo", () => {
+ test("renders custom workspace logo when present", () => {
+ mocks.useVueState.mockReturnValue("https://example.com/logo.png");
+ const { container, render, unmount } = renderIntoContainer(<BytebaseLogo />);
+ render();
+ const img = container.querySelector("img");
+ expect(img).not.toBeNull();
+ expect(img?.getAttribute("src")).toBe("https://example.com/logo.png");
+ expect(img?.getAttribute("alt")).toBe("branding logo");
+ unmount();
+ });
+
+ test("renders fallback Bytebase SVG when workspace has no custom logo", () => {
+ mocks.useVueState.mockReturnValue("");
+ const { container, render, unmount } = renderIntoContainer(<BytebaseLogo />);
+ render();
+ const img = container.querySelector("img");
+ expect(img).not.toBeNull();
+ expect(img?.getAttribute("src")).toBe("/assets/logo-full.svg");
+ expect(img?.getAttribute("alt")).toBe("Bytebase");
+ unmount();
+ });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run:
+```bash
+pnpm --dir frontend test -- BytebaseLogo.test --run
+```
+
+Expected: FAIL with "Cannot find module './BytebaseLogo'".
+
+- [ ] **Step 3: Write the minimal implementation**
+
+Create `frontend/src/react/components/BytebaseLogo.tsx`:
+
+```tsx
+import logoFull from "@/assets/logo-full.svg";
+import { useVueState } from "@/react/hooks/useVueState";
+import { useWorkspaceV1Store } from "@/store";
+
+type Props = {
+ /** Optional route name — when set, the logo is wrapped in a link that records the visit. */
+ readonly redirect?: string;
+};
+
+/**
+ * Replaces frontend/src/components/BytebaseLogo.vue. Shows the workspace's
+ * custom logo when set, otherwise the bundled Bytebase fallback SVG.
+ *
+ * The `redirect` prop is supported for future callers. It is not used by
+ * the SQL Editor Welcome screen. Router-link behavior will be added when
+ * the first React caller needs it.
+ */
+export function BytebaseLogo(_props: Props) {
+ const customLogo = useVueState(
+ () => useWorkspaceV1Store().currentWorkspace?.logo ?? ""
+ );
+
+ return (
+ <div className="shrink-0 max-w-44 flex items-center overflow-hidden">
+ <span className="h-full w-full select-none flex flex-row justify-center items-center">
+ {customLogo ? (
+ <img
+ src={customLogo}
+ alt="branding logo"
+ className="h-full object-contain"
+ />
+ ) : (
+ <img
+ src={logoFull}
+ alt="Bytebase"
+ className="h-8 md:h-10 w-auto object-contain"
+ />
+ )}
+ </span>
+ </div>
+ );
+}
+```
+
+Note: The `redirect`/router-link branch from the Vue original is intentionally omitted for now. Welcome does not use it, and adding React Router link support requires more wiring. When a future caller needs it, extend this file.
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run:
+```bash
+pnpm --dir frontend test -- BytebaseLogo.test --run
+```
+
+Expected: PASS (2 tests).
+
+- [ ] **Step 5: Stop for user review**
+
+Report: "BytebaseLogo.tsx + test created and passing. Ready for commit."
+
+---
+
+## Task 3: Create `WelcomeButton.tsx` (TDD)
+
+**Goal:** A big square button with vertical icon-over-label layout. Mirrors `frontend/src/views/sql-editor/EditorPanel/Welcome/Button.vue` which wraps naive-ui's `NButton` with custom slot layout (height `7rem`, min-width `7rem`, vertical flex with `gap-2`).
+
+**Files:**
+- Create: `frontend/src/react/components/sql-editor/WelcomeButton.tsx`
+- Create: `frontend/src/react/components/sql-editor/WelcomeButton.test.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `frontend/src/react/components/sql-editor/WelcomeButton.test.tsx`:
+
+```tsx
+import type { ReactElement } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+let WelcomeButton: typeof import("./WelcomeButton").WelcomeButton;
+
+const renderIntoContainer = (element: ReactElement) => {
+ const container = document.createElement("div");
+ const root = createRoot(container);
+ document.body.appendChild(container);
+ return {
+ container,
+ render: () => {
+ act(() => {
+ root.render(element);
+ });
+ },
+ unmount: () => {
+ act(() => {
+ root.unmount();
+ });
+ container.remove();
+ },
+ };
+};
+
+beforeEach(async () => {
+ ({ WelcomeButton } = await import("./WelcomeButton"));
+});
+
+describe("WelcomeButton", () => {
+ test("renders icon above label", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <WelcomeButton icon={<span data-testid="icon">I</span>}>
+ Hello
+ </WelcomeButton>
+ );
+ render();
+ const button = container.querySelector("button");
+ expect(button?.textContent).toContain("Hello");
+ expect(container.querySelector('[data-testid="icon"]')).not.toBeNull();
+ unmount();
+ });
+
+ test("invokes onClick when clicked", () => {
+ const handler = vi.fn();
+ const { container, render, unmount } = renderIntoContainer(
+ <WelcomeButton icon={<span>I</span>} onClick={handler}>
+ Click
+ </WelcomeButton>
+ );
+ render();
+ const button = container.querySelector("button");
+ act(() => {
+ button?.click();
+ });
+ expect(handler).toHaveBeenCalledTimes(1);
+ unmount();
+ });
+
+ test("applies primary variant classes by default", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <WelcomeButton icon={<span>I</span>}>Primary</WelcomeButton>
+ );
+ render();
+ const button = container.querySelector("button");
+ expect(button?.className).toContain("bg-accent");
+ unmount();
+ });
+
+ test("applies secondary variant classes when variant='secondary'", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <WelcomeButton icon={<span>I</span>} variant="secondary">
+ Secondary
+ </WelcomeButton>
+ );
+ render();
+ const button = container.querySelector("button");
+ expect(button?.className).toContain("border-control-border");
+ unmount();
+ });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run:
+```bash
+pnpm --dir frontend test -- WelcomeButton.test --run
+```
+
+Expected: FAIL with "Cannot find module './WelcomeButton'".
+
+- [ ] **Step 3: Write the minimal implementation**
+
+Create `frontend/src/react/components/sql-editor/WelcomeButton.tsx`:
+
+```tsx
+import { Button as BaseButton } from "@base-ui/react/button";
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "@/react/lib/utils";
+
+/**
+ * Big square icon-over-label button used on the SQL Editor Welcome screen.
+ * Mirrors frontend/src/views/sql-editor/EditorPanel/Welcome/Button.vue,
+ * which wraps NButton at 7rem × 7rem with a vertical flex content slot.
+ */
+const welcomeButtonVariants = cva(
+ "inline-flex flex-col items-center justify-center gap-2 min-w-28 h-28 px-4 rounded-xs text-sm font-medium cursor-pointer transition-colors focus:outline-hidden focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+ {
+ variants: {
+ variant: {
+ primary: "bg-accent text-accent-text hover:bg-accent-hover",
+ secondary:
+ "border border-control-border bg-transparent text-control hover:bg-control-bg",
+ },
+ },
+ defaultVariants: {
+ variant: "primary",
+ },
+ }
+);
+
+type WelcomeButtonProps = Omit<ComponentProps<"button">, "children"> &
+ VariantProps<typeof welcomeButtonVariants> & {
+ readonly icon: ReactNode;
+ readonly children: ReactNode;
+ };
+
+export function WelcomeButton({
+ icon,
+ children,
+ variant,
+ className,
+ ref,
+ ...props
+}: WelcomeButtonProps) {
+ return (
+ <BaseButton
+ ref={ref}
+ className={cn(welcomeButtonVariants({ variant, className }))}
+ {...props}
+ >
+ <span className="flex items-center justify-center">{icon}</span>
+ <span>{children}</span>
+ </BaseButton>
+ );
+}
+```
+
+Note on sizing: Vue's original uses `--n-height: 7rem` and `min-width: 7rem`. Tailwind's `h-28` is exactly `7rem` (112px); `min-w-28` is `7rem`. The visual result matches.
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run:
+```bash
+pnpm --dir frontend test -- WelcomeButton.test --run
+```
+
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Stop for user review**
+
+Report: "WelcomeButton.tsx + test created and passing. Ready for commit."
+
+---
+
+## Task 4: Create `Welcome.tsx` (TDD)
+
+**Goal:** The React leaf replacing `Welcome.vue`. Renders `BytebaseLogo` + two conditionally-visible `WelcomeButton`s. "Add a new instance" is gated by `bb.instances.create` and routes via `router.push({ name: INSTANCE_ROUTE_DASHBOARD, hash: "#add" })`. "Connect to a database" is gated by `bb.sql.select` against the current SQL Editor project and calls the `onChangeConnection` prop.
+
+**Files:**
+- Create: `frontend/src/react/components/sql-editor/Welcome.tsx`
+- Create: `frontend/src/react/components/sql-editor/Welcome.test.tsx`
+
+- [ ] **Step 1: Write the failing test**
+
+Create `frontend/src/react/components/sql-editor/Welcome.test.tsx`:
+
+```tsx
+import type { ReactElement } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mocks = vi.hoisted(() => ({
+ useTranslation: vi.fn(() => ({ t: (key: string) => key })),
+ usePermissionCheck: vi.fn<
+ (perms: readonly string[], project?: unknown) => [boolean, string | undefined]
+ >(),
+ useVueState: vi.fn<(getter: () => unknown) => unknown>(),
+ routerPush: vi.fn(),
+}));
+
+vi.mock("react-i18next", () => ({
+ useTranslation: mocks.useTranslation,
+}));
+
+vi.mock("@/react/components/PermissionGuard", () => ({
+ usePermissionCheck: mocks.usePermissionCheck,
+}));
+
+vi.mock("@/react/hooks/useVueState", () => ({
+ useVueState: mocks.useVueState,
+}));
+
+vi.mock("@/router", () => ({
+ router: { push: mocks.routerPush },
+}));
+
+vi.mock("@/router/dashboard/workspaceRoutes", () => ({
+ INSTANCE_ROUTE_DASHBOARD: "workspace.instance",
+}));
+
+vi.mock("@/store", () => ({
+ useSQLEditorStore: vi.fn(),
+ useProjectV1Store: vi.fn(),
+ useWorkspaceV1Store: vi.fn(),
+}));
+
+vi.mock("@/assets/logo-full.svg", () => ({
+ default: "/assets/logo-full.svg",
+}));
+
+let Welcome: typeof import("./Welcome").Welcome;
+
+const renderIntoContainer = (element: ReactElement) => {
+ const container = document.createElement("div");
+ const root = createRoot(container);
+ document.body.appendChild(container);
+ return {
+ container,
+ render: () => {
+ act(() => {
+ root.render(element);
+ });
+ },
+ unmount: () => {
+ act(() => {
+ root.unmount();
+ });
+ container.remove();
+ },
+ };
+};
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ // Default: workspace logo empty, both permissions granted.
+ mocks.useVueState.mockReturnValue("");
+ mocks.usePermissionCheck.mockReturnValue([true, undefined]);
+ ({ Welcome } = await import("./Welcome"));
+});
+
+describe("Welcome", () => {
+ test("renders both buttons when both permissions present", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ expect(container.textContent).toContain("sql-editor.add-a-new-instance");
+ expect(container.textContent).toContain("sql-editor.connect-to-a-database");
+ unmount();
+ });
+
+ test("hides Add-Instance when missing bb.instances.create", () => {
+ mocks.usePermissionCheck.mockImplementation((perms) => {
+ if (perms.includes("bb.instances.create")) return [false, "missing"];
+ return [true, undefined];
+ });
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ expect(container.textContent).not.toContain("sql-editor.add-a-new-instance");
+ expect(container.textContent).toContain("sql-editor.connect-to-a-database");
+ unmount();
+ });
+
+ test("hides Connect when missing bb.sql.select", () => {
+ mocks.usePermissionCheck.mockImplementation((perms) => {
+ if (perms.includes("bb.sql.select")) return [false, "missing"];
+ return [true, undefined];
+ });
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ expect(container.textContent).toContain("sql-editor.add-a-new-instance");
+ expect(container.textContent).not.toContain("sql-editor.connect-to-a-database");
+ unmount();
+ });
+
+ test("hides both buttons when neither permission present", () => {
+ mocks.usePermissionCheck.mockReturnValue([false, "missing"]);
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ expect(container.querySelectorAll("button")).toHaveLength(0);
+ unmount();
+ });
+
+ test("routes to instance dashboard with #add hash on Add-Instance click", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ const buttons = container.querySelectorAll("button");
+ // Add-Instance is the first button (matches Vue order).
+ act(() => {
+ (buttons[0] as HTMLButtonElement).click();
+ });
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.instance",
+ hash: "#add",
+ });
+ unmount();
+ });
+
+ test("invokes onChangeConnection on Connect click", () => {
+ const onChangeConnection = vi.fn();
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={onChangeConnection} />
+ );
+ render();
+ const buttons = container.querySelectorAll("button");
+ // Connect is the second button (matches Vue order).
+ act(() => {
+ (buttons[1] as HTMLButtonElement).click();
+ });
+ expect(onChangeConnection).toHaveBeenCalledTimes(1);
+ unmount();
+ });
+});
+```
+
+- [ ] **Step 2: Run the test to verify it fails**
+
+Run:
+```bash
+pnpm --dir frontend test -- Welcome.test --run
+```
+
+Expected: FAIL with "Cannot find module './Welcome'".
+
+- [ ] **Step 3: Write the minimal implementation**
+
+Create `frontend/src/react/components/sql-editor/Welcome.tsx`:
+
+```tsx
+import { LayersIcon, LinkIcon } from "lucide-react";
+import { useTranslation } from "react-i18next";
+import { BytebaseLogo } from "@/react/components/BytebaseLogo";
+import { usePermissionCheck } from "@/react/components/PermissionGuard";
+import { useVueState } from "@/react/hooks/useVueState";
+import { router } from "@/router";
+import { INSTANCE_ROUTE_DASHBOARD } from "@/router/dashboard/workspaceRoutes";
+import { useProjectV1Store, useSQLEditorStore } from "@/store";
+import { WelcomeButton } from "./WelcomeButton";
+
+export type WelcomeProps = {
+ /**
+ * Called when the user clicks "Connect to a database". Vue parent
+ * passes a callback that sets `asidePanelTab = "SCHEMA"` and
+ * `showConnectionPanel = true` on the Vue-side SQL Editor context.
+ */
+ readonly onChangeConnection: () => void;
+};
+
+export function Welcome({ onChangeConnection }: WelcomeProps) {
+ const { t } = useTranslation();
+
+ const project = useVueState(() => {
+ const projectName = useSQLEditorStore().project;
+ return projectName
+ ? useProjectV1Store().getProjectByName(projectName)
+ : undefined;
+ });
+
+ const [showCreateInstanceButton] = usePermissionCheck([
+ "bb.instances.create",
+ ]);
+ const [showConnectButton] = usePermissionCheck(["bb.sql.select"], project);
+
+ const handleCreateInstance = () => {
+ router.push({
+ name: INSTANCE_ROUTE_DASHBOARD,
+ hash: "#add",
+ });
+ };
+
+ return (
+ <div className="w-full flex-1 flex flex-col items-center justify-center gap-y-4">
+ <BytebaseLogo />
+ <div className="flex items-center flex-wrap gap-4">
+ {showCreateInstanceButton && (
+ <WelcomeButton
+ variant="secondary"
+ icon={<LayersIcon strokeWidth={1.5} className="size-8" />}
+ onClick={handleCreateInstance}
+ >
+ {t("sql-editor.add-a-new-instance")}
+ </WelcomeButton>
+ )}
+ {showConnectButton && (
+ <WelcomeButton
+ variant="primary"
+ icon={<LinkIcon strokeWidth={1.5} className="size-8" />}
+ onClick={onChangeConnection}
+ >
+ {t("sql-editor.connect-to-a-database")}
+ </WelcomeButton>
+ )}
+ </div>
+ </div>
+ );
+}
+```
+
+Note on variant mapping: The Vue original uses `type="default"` for Add-Instance (which renders like a bordered/secondary button) and `secondary` + `type="primary"` for Connect (which renders as the accent-filled primary). In our simpler 2-variant model: Add-Instance → `secondary`, Connect → `primary`. Verify visually during Task 8.
+
+- [ ] **Step 4: Run the test to verify it passes**
+
+Run:
+```bash
+pnpm --dir frontend test -- Welcome.test --run
+```
+
+Expected: PASS (6 tests).
+
+- [ ] **Step 5: Stop for user review**
+
+Report: "Welcome.tsx + test created and passing. Ready for commit."
+
+---
+
+## Task 5: Register the new glob in `mount.ts`
+
+**Goal:** Make `<ReactPageMount page="Welcome" />` resolve the new file at `frontend/src/react/components/sql-editor/Welcome.tsx`.
+
+**Files:**
+- Modify: `frontend/src/react/mount.ts:1-18` and `:52-58`
+
+- [ ] **Step 1: Read current state**
+
+Open `frontend/src/react/mount.ts`. Confirm the current `pageLoaders` and `pageDirs` structure matches what's described below.
+
+- [ ] **Step 2: Add the SQL Editor glob**
+
+Change the top of the file from:
+
+```ts
+const settingsPageLoaders = import.meta.glob("./pages/settings/*.tsx");
+const projectPageLoaders = import.meta.glob("./pages/project/*.tsx");
+const pluginComponentLoaders = import.meta.glob(
+ "./plugins/agent/components/AgentWindow.tsx"
+);
+const workspacePageLoaders = import.meta.glob("./pages/workspace/*.tsx");
+const authComponentLoaders = import.meta.glob(
+ "./components/auth/SessionExpiredSurface.tsx"
+);
+const pageLoaders = {
+ ...settingsPageLoaders,
+ ...projectPageLoaders,
+ ...pluginComponentLoaders,
+ ...workspacePageLoaders,
+ ...authComponentLoaders,
+};
+```
+
+To:
+
+```ts
+const settingsPageLoaders = import.meta.glob("./pages/settings/*.tsx");
+const projectPageLoaders = import.meta.glob("./pages/project/*.tsx");
+const pluginComponentLoaders = import.meta.glob(
+ "./plugins/agent/components/AgentWindow.tsx"
+);
+const workspacePageLoaders = import.meta.glob("./pages/workspace/*.tsx");
+const authComponentLoaders = import.meta.glob(
+ "./components/auth/SessionExpiredSurface.tsx"
+);
+const sqlEditorComponentLoaders = import.meta.glob(
+ "./components/sql-editor/*.tsx"
+);
+const pageLoaders = {
+ ...settingsPageLoaders,
+ ...projectPageLoaders,
+ ...pluginComponentLoaders,
+ ...workspacePageLoaders,
+ ...authComponentLoaders,
+ ...sqlEditorComponentLoaders,
+};
+```
+
+Then change `pageDirs` from:
+
+```ts
+const pageDirs = [
+ "./pages/settings",
+ "./pages/project",
+ "./plugins/agent/components",
+ "./pages/workspace",
+ "./components/auth",
+];
+```
+
+To:
+
+```ts
+const pageDirs = [
+ "./pages/settings",
+ "./pages/project",
+ "./plugins/agent/components",
+ "./pages/workspace",
+ "./components/auth",
+ "./components/sql-editor",
+];
+```
+
+Important: The `*.tsx` glob also matches `*.test.tsx` and internal building blocks like `WelcomeButton.tsx` — every file resolves into `pageLoaders`. That is safe because `resolveReactPagePath` requires the caller to pass the explicit basename as the `page` string (e.g. `page="Welcome"`), and nobody will type `page="Welcome.test"` or `page="WelcomeButton"`. This matches the behavior of the existing `pages/settings/*.tsx` glob, which also picks up test files (`environmentSelection.test.tsx`) and non-page utilities (`environmentSelection.ts`) without issue. If a stricter filter becomes valuable later, add an exclusion pattern to the glob — deferred for now.
+
+- [ ] **Step 3: Run type-check**
+
+Run:
+```bash
+pnpm --dir frontend type-check
+```
+
+Expected: pass. (`mount.ts` has no semantic changes, just new glob strings.)
+
+- [ ] **Step 4: Stop for user review**
+
+Report: "mount.ts updated with ./components/sql-editor glob. Ready for commit."
+
+---
+
+## Task 6: Swap `StandardPanel.vue` to use `ReactPageMount`
+
+**Goal:** Replace `<Welcome v-else />` inside `EditorPanel/StandardPanel/StandardPanel.vue` with `<ReactPageMount v-else page="Welcome" :on-change-connection="changeConnection" />`. Pull the Vue-context-coupled action (`changeConnection`) up to this component since `Welcome` no longer has direct access to `useSQLEditorContext`.
+
+**Files:**
+- Modify: `frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue:55` (template) and `:98,105-106` (script)
+
+- [ ] **Step 1: Read the current state**
+
+Open `frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue`. Confirm:
+
+- Line 55: `<Welcome v-else />`
+- Line 90: `import { useSQLEditorContext } from "../../context";`
+- Line 98: `import Welcome from "../Welcome";`
+- Line 105-106: `const { showAIPanel, editorPanelSize, handleEditorPanelResize } = useSQLEditorContext();`
+
+- [ ] **Step 2: Replace the template, import, and destructure**
+
+Change line 55 from:
+
+```vue
+<Welcome v-else />
+```
+
+To:
+
+```vue
+<ReactPageMount
+ v-else
+ page="Welcome"
+ :on-change-connection="changeConnection"
+/>
+```
+
+Change line 98 from:
+
+```ts
+import Welcome from "../Welcome";
+```
+
+To:
+
+```ts
+import ReactPageMount from "@/react/ReactPageMount.vue";
+```
+
+Change lines 105-106 from:
+
+```ts
+const { showAIPanel, editorPanelSize, handleEditorPanelResize } =
+ useSQLEditorContext();
+```
+
+To:
+
+```ts
+const {
+ showAIPanel,
+ editorPanelSize,
+ handleEditorPanelResize,
+ showConnectionPanel,
+ asidePanelTab,
+} = useSQLEditorContext();
+
+const changeConnection = () => {
+ asidePanelTab.value = "SCHEMA";
+ showConnectionPanel.value = true;
+};
+```
+
+- [ ] **Step 3: Run type-check**
+
+Run:
+```bash
+pnpm --dir frontend type-check
+```
+
+Expected: pass. The new import path, the added destructure fields, and the new `changeConnection` function are all existing API surface. `ReactPageMount.vue` accepts arbitrary `attrs` via `useAttrs()` so the kebab-case prop is passed through.
+
+- [ ] **Step 4: Run the React i18n consistency check**
+
+Run:
+```bash
+node frontend/scripts/check-react-i18n.mjs
+```
+
+Expected: pass (the two keys added in Task 1 now have a consumer in `Welcome.tsx`).
+
+- [ ] **Step 5: Start the dev server and smoke-test UX parity**
+
+Run (in a background terminal):
+```bash
+pnpm --dir frontend dev
+```
+
+Then in the browser, open the SQL Editor route and verify:
+
+1. Open `/sql-editor` with no active connection → Welcome renders with: Bytebase logo at top, 2 buttons ("Add new instance" + "Connect to database") below.
+2. Click "Add new instance" → navigates to `/instance#add`.
+3. Go back to `/sql-editor`. Click "Connect to database" → connection panel opens on the right AND the aside panel switches to the SCHEMA tab.
+4. Toggle the app language (English ↔ Chinese) → button labels update.
+5. Workspace with custom logo → the custom logo renders in place of the Bytebase SVG. (Temporarily set one in `Settings → General → Logo` to verify.)
+6. Sign in as a viewer-only user (no `bb.instances.create`) → only the "Connect to a database" button shows.
+7. Sign in as a user without `bb.sql.select` → only the "Add new instance" button shows. (May require an account with workspace admin but no project role.)
+
+For each state, take a side-by-side screenshot against the pre-change Vue version (you can capture this by stashing Task 6 changes locally: `git stash push frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue`, screenshot, `git stash pop`).
+
+Document each state with a screenshot for the PR description.
+
+- [ ] **Step 6: Stop for user review**
+
+Report: "StandardPanel.vue swapped to ReactPageMount. Dev server smoke test PASSED/FAILED (with notes). Screenshots captured. Ready for commit."
+
+---
+
+## Task 7: Verify orphan status and delete the Vue `Welcome/` directory
+
+**Goal:** Confirm no other live caller imports from `EditorPanel/Welcome/`, then delete the orphaned Vue files per playbook §Deletion.
+
+**Files:**
+- Delete: `frontend/src/views/sql-editor/EditorPanel/Welcome/Welcome.vue`
+- Delete: `frontend/src/views/sql-editor/EditorPanel/Welcome/Button.vue`
+- Delete: `frontend/src/views/sql-editor/EditorPanel/Welcome/index.ts`
+- Delete: `frontend/src/views/sql-editor/EditorPanel/Welcome/` (the now-empty directory)
+
+- [ ] **Step 1: Search for remaining callers**
+
+Use Grep (or ripgrep directly if needed):
+
+Search pattern 1 — imports of the directory:
+```
+from ['\"].*EditorPanel/Welcome['\"]
+```
+Scope: `frontend/src`.
+
+Search pattern 2 — imports of specific files:
+```
+from ['\"].*EditorPanel/Welcome/Welcome['\"]
+from ['\"].*EditorPanel/Welcome/Button['\"]
+```
+Scope: `frontend/src`.
+
+Search pattern 3 — the Vue component tag:
+```
+<Welcome[\\s/>]
+```
+Scope: `frontend/src/views/sql-editor`. (Filter the Vue files — the `Welcome.tsx` in React is not relevant here.)
+
+Expected: After Task 6, all three patterns return **zero matches outside the files being deleted**. If any caller remains, stop and investigate — do NOT delete.
+
+- [ ] **Step 2: Delete the files**
+
+Run:
+```bash
+rm -rf frontend/src/views/sql-editor/EditorPanel/Welcome
+```
+
+- [ ] **Step 3: Run type-check and test**
+
+Run:
+```bash
+pnpm --dir frontend type-check
+pnpm --dir frontend test --run
+```
+
+Expected: both pass. If type-check fails with "cannot find module ../Welcome", Task 6's import change was missed — revisit.
+
+- [ ] **Step 4: Stop for user review**
+
+Report: "Vue Welcome directory deleted. Type-check and tests pass. Ready for commit."
+
+---
+
+## Task 8: Final verification
+
+**Goal:** Run the full verification suite before the PR is opened.
+
+- [ ] **Step 1: Run auto-fix**
+
+Run:
+```bash
+pnpm --dir frontend fix
+```
+
+Expected: no changes, or only trivial formatting adjustments to the new files.
+
+- [ ] **Step 2: Run the CI-equivalent check**
+
+Run:
+```bash
+pnpm --dir frontend check
+```
+
+Expected: pass (ESLint + Biome + React i18n consistency).
+
+- [ ] **Step 3: Run type-check**
+
+Run:
+```bash
+pnpm --dir frontend type-check
+```
+
+Expected: pass. This covers both the Vue tsconfig (via `vue-tsc`) and the React tsconfig (`tsconfig.react.json`).
+
+- [ ] **Step 4: Run the full test suite**
+
+Run:
+```bash
+pnpm --dir frontend test --run
+```
+
+Expected: all tests pass — existing + the 3 new test files (`BytebaseLogo.test.tsx`, `WelcomeButton.test.tsx`, `Welcome.test.tsx`).
+
+- [ ] **Step 5: Manual UX-parity screenshot capture**
+
+Confirm screenshots from Task 6 Step 5 cover these five states:
+
+1. Workspace with custom logo.
+2. Workspace with fallback Bytebase SVG.
+3. User missing `bb.instances.create` → only Connect button.
+4. User missing `bb.sql.select` → only Add-Instance button.
+5. User with both permissions → both buttons.
+
+Each screenshot should have a corresponding side-by-side with the pre-change Vue version.
+
+- [ ] **Step 6: Stop for user review**
+
+Final report template:
+
+```
+Stage 1 complete.
+
+Summary:
+- Added 2 i18n keys to 5 React locales
+- Created: BytebaseLogo.tsx, WelcomeButton.tsx, Welcome.tsx (+ 3 test files)
+- Modified: mount.ts (1 new glob), StandardPanel.vue (import + destructure + changeConnection)
+- Deleted: frontend/src/views/sql-editor/EditorPanel/Welcome/ (3 files)
+
+Verification:
+- pnpm fix: clean
+- pnpm check: pass
+- pnpm type-check: pass
+- pnpm test: all pass (N tests, M new)
+- Manual UX parity: 5 states verified with screenshots (attached)
+
+Ready for PR.
+```
diff --git a/docs/superpowers/specs/2026-04-20-sql-editor-react-migration-stage-1-design.md b/docs/superpowers/specs/2026-04-20-sql-editor-react-migration-stage-1-design.md
new file mode 100644
index 0000000000..37c5142b97
--- /dev/null
+++ b/docs/superpowers/specs/2026-04-20-sql-editor-react-migration-stage-1-design.md
@@ -0,0 +1,160 @@
+# SQL Editor React Migration — Stage 1 Design
+
+**Date:** 2026-04-20
+**Author:** [email protected]
+**Status:** Draft
+
+## 1. Goal
+
+Begin the Vue→React migration of the SQL Editor by establishing the React-island-in-Vue pattern at a non-route boundary, with one tiny leaf as the first proof. Every step preserves UX exactly.
+
+## 2. Non-goals (Stage 1)
+
+- Migrating Monaco, ResultView, AsidePanel, ConnectionPanel, TabList, or any panel under `EditorPanel/Panels/`.
+- Refactoring `useSQLEditorContext` into a Pinia store. Deferred to the first stage where it is justified — see §9.
+- Flipping the SQL Editor route or layout to React.
+- Changing any Vue file that does not sit on the Welcome call path.
+
+## 3. Architecture
+
+The SQL Editor under `frontend/src/views/sql-editor/` is **147 Vue + 68 TS files**, organized as a single-page app rather than a multi-route subsystem. All five `/sql-editor/...` routes mount the same `SQLEditorPage.vue`, which is wrapped by `SQLEditorLayout.vue` and depends on deep `provide/inject` context (`useSQLEditorContext`, `Sheet` context, `TabList` context), Pinia stores, an Emittery event bus, and Monaco. There is no sub-route boundary to flip.
+
+We adopt **bottom-up React islands inside Vue**:
+
+- Keep the Vue orchestrator (`SQLEditorLayout`, `SQLEditorPage`, `SQLEditorHomePage`), all `provide/inject` contexts, all Pinia stores, and the Emittery bus.
+- Embed React leaves inline inside the Vue tree using the existing `frontend/src/react/ReactPageMount.vue` (already supports component mounting, not just routes — `mount.ts` already maps `./components/auth/SessionExpiredSurface.tsx` alongside the `pages/*` globs).
+- Each new React leaf is registered through a new `./components/sql-editor/*.tsx` glob in `mount.ts`.
+- React leaves access Pinia stores and the router directly per the `2026-04-08-react-migration-playbook.md`. For Vue-`provide/inject`-only state (e.g., `showConnectionPanel`), the Vue parent passes a callback prop (Hybrid C — see §5).
+
+This direction matches the existing migration playbook and lets every step be independently verifiable side-by-side. The cost is a one-time investment in registering a non-`pages/` glob in `mount.ts`; thereafter every leaf migration is mechanical.
+
+## 4. Stage 1 work — migrate `EditorPanel/Welcome/Welcome.vue`
+
+The first leaf is `frontend/src/views/sql-editor/EditorPanel/Welcome/Welcome.vue` (77 lines). It renders when no database connection exists: a `BytebaseLogo` plus two large square buttons ("Add a new instance" and "Connect to a database"), each gated by a permission. It is the smallest real component in the SQL Editor that exercises every cross-cutting concern we need to solve once: Pinia from React, router from React, permission checks, i18n, an extracted shared component, and exactly one Vue-context-coupled action.
+
+### 4.1 New React files
+
+| File | Purpose | Notes |
+|---|---|---|
+| `frontend/src/react/components/sql-editor/Welcome.tsx` | Replaces `Welcome.vue`. | Reads project + permissions from React-side hooks. Receives `onChangeConnection` callback as a prop (see §5). |
+| `frontend/src/react/components/sql-editor/WelcomeButton.tsx` | Replaces local `Button.vue` (28 lines wrapping `NButton`). | Mirrors Vue's structure per the extract-common-component policy. Built on shadcn `Button` with a `cva` variant matching the NButton dimensions: height 7rem, min-width 7rem, vertical icon-over-label layout. Lives next to Welcome since it is not yet reused elsewhere. |
+| `frontend/src/react/components/BytebaseLogo.tsx` | Replaces `frontend/src/components/BytebaseLogo.vue`. Used here without the `redirect` prop, but built fully so future React pages can reuse. | Reads `useWorkspaceV1Store` directly from React (via `useVueState`). Renders the workspace logo or the bundled SVG fallback (`@/assets/logo-full.svg`). The optional `redirect` branch uses React Router only when needed; Welcome does not pass it. |
+
+### 4.2 Vue caller modified
+
+The single live caller of `<Welcome />` is `frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue`:
+
+- line 55: `<Welcome v-else />`
+- line 98: `import Welcome from "../Welcome";`
+
+(`EditorPanel/Welcome/index.ts` is just a re-export wrapper.)
+
+Swap to:
+
+```vue
+<ReactPageMount v-else page="Welcome" :on-change-connection="changeConnection" />
+```
+
+`StandardPanel.vue` already destructures `useSQLEditorContext()` (currently for `showAIPanel`, `editorPanelSize`, `handleEditorPanelResize` at line 105-106). Add `showConnectionPanel` and `asidePanelTab` to that destructure and construct:
+
+```ts
+const changeConnection = () => {
+ asidePanelTab.value = "SCHEMA";
+ showConnectionPanel.value = true;
+};
+```
+
+Replace the Vue `import Welcome from "../Welcome"` with `import ReactPageMount from "@/react/ReactPageMount.vue"` (or whichever import path is used elsewhere — there are existing precedents).
+
+The `gotoInstanceCreatePage` action lives inside React (it is just a `router.push`, no Vue context dependency).
+
+### 4.3 Mount infrastructure
+
+`frontend/src/react/mount.ts`:
+
+- Add `const sqlEditorComponentLoaders = import.meta.glob("./components/sql-editor/*.tsx");`
+- Spread it into `pageLoaders`.
+- Add `"./components/sql-editor"` to `pageDirs`.
+
+Variable name `pageDirs` stays — renaming to `componentDirs` is a separate cleanup with no functional value.
+
+### 4.4 Vue file deletion
+
+After the `StandardPanel.vue` swap, the entire `frontend/src/views/sql-editor/EditorPanel/Welcome/` directory (`Welcome.vue` + `Button.vue` + `index.ts`) becomes orphaned because `StandardPanel.vue` will import `ReactPageMount` directly instead of `from "../Welcome"`. Per playbook §Deletion: run `rg "from.*EditorPanel/Welcome"` and `rg "import.*Welcome\.vue"` to confirm zero remaining callers, then delete the entire `Welcome/` subdirectory.
+
+## 5. Data flow & context bridge for Welcome
+
+| What Welcome needs | Source | How React gets it |
+|---|---|---|
+| Workspace logo / fallback SVG | `useWorkspaceV1Store` (Pinia) | Direct Pinia import + `useVueState` (read-only subscription) inside `BytebaseLogo`. |
+| Project (for `bb.sql.select` permission scope) | `useSQLEditorStore` (Pinia, `project` ref) → `useProjectV1Store.getProjectByName` | Direct Pinia import + `useVueState`. |
+| `bb.instances.create` workspace permission | `hasWorkspacePermissionV2` | `usePermissionCheck(["bb.instances.create"])` (React-native hook from playbook). |
+| `bb.sql.select` project permission | `hasProjectPermissionV2(project, ...)` | `usePermissionCheck(["bb.sql.select"], { project })` — same hook with project scope. |
+| Navigate to instance create | `router.push({ name: INSTANCE_ROUTE_DASHBOARD, hash: '#add' })` | Direct router import inside React (playbook-approved). |
+| Open connection panel + switch to SCHEMA tab | `useSQLEditorContext()` — Vue `provide/inject` only | Vue parent computes `changeConnection = () => { asidePanelTab.value = 'SCHEMA'; showConnectionPanel.value = true }` and passes it as the `onChangeConnection` prop. This is the only prop-callback Welcome receives. |
+
+**Why this surface:** Welcome touches Vue-context state in exactly one place (`changeConnection`). Everything else is Pinia-or-router, both of which React can call directly per the playbook. So we get a 1-prop interface — minimal coupling, no premature Pinia bridge for `useSQLEditorContext`.
+
+## 6. Verification & UX parity
+
+### 6.1 Per-leaf verification (run before opening the Stage 1 PR)
+
+- `pnpm --dir frontend fix` — auto-format + lint
+- `pnpm --dir frontend check` — CI-equivalent check
+- `pnpm --dir frontend type-check` — covers both Vue (`vue-tsc`) and React (`tsconfig.react.json`) tsconfigs
+- `pnpm --dir frontend test` — unit tests
+- New focused unit tests:
+ - `WelcomeButton.test.tsx` — variant rendering, click handler.
+ - `Welcome.test.tsx` — renders both buttons when both permissions present, hides Add-Instance when missing `bb.instances.create`, hides Connect when missing `bb.sql.select`, calls `onChangeConnection` on click.
+ - Pattern matches existing `FeatureAttention.test.tsx` and `dialog.test.tsx`.
+
+### 6.2 UX parity verification (manual, in a running dev server)
+
+- Open SQL Editor with no connection → Welcome renders with: BytebaseLogo at top, "Add a new instance" + "Connect to a database" buttons below in a wrapped flex.
+- Side-by-side screenshot comparison vs. the Vue version for these states:
+ - (a) workspace with custom logo
+ - (b) workspace using fallback Bytebase SVG
+ - (c) viewer-only role (only Connect button visible)
+ - (d) admin role (both buttons visible)
+ - (e) viewer with no `bb.sql.select` (no buttons at all)
+- Click "Add a new instance" → routes to `/instance#add`.
+- Click "Connect to a database" → opens the connection panel and switches the aside panel to SCHEMA tab (verifies the `onChangeConnection` callback wires correctly).
+- Locale switch (English ↔ Chinese) → labels update without remount artifacts (the `ReactPageMount` locale-watch handler covers this; just confirm visually).
+
+### 6.3 i18n
+
+Welcome's strings (`sql-editor.add-a-new-instance`, `sql-editor.connect-to-a-database`) already exist in `frontend/src/locales/`. Verify they are also resolvable by the React i18n loader (`frontend/src/react/locales/`). If not, add them per playbook §i18n.
+
+## 7. Out of scope for Stage 1 (explicit deferrals)
+
+- **Pinia bridge for `useSQLEditorContext`.** Welcome only needs one prop-callback. We design the Pinia bridge in Stage 2 against a real consumer (likely `InfoPanel`) so the shape is not speculative.
+- **Emittery events bridge** (e.g., `alter-schema`, `insert-at-caret`, `set-editor-selection`). Welcome does not emit or listen to any. First needed when migrating components inside `EditorPanel` proper.
+- **Monaco React wrapper.** Hardest piece per the playbook (CI-only failure path under Node 24 from direct `import("monaco-editor")` inside React effects). Build a stable integration seam when migrating the editor — not before.
+- **`ReactPageMount.vue` rename to `ReactComponentMount.vue`.** Convention-only cleanup; defer until a rename has zero functional value to land alongside other work.
+
+## 8. Future stage sketch (informational only — each stage gets its own brainstorm + spec + plan)
+
+| Stage | Scope | Why this order |
+|---|---|---|
+| **1 (this spec)** | `Welcome` leaf | Smallest leaf that exercises Pinia + router + permission + i18n + extracted child component. |
+| **2** | One read-only panel under `EditorPanel/Panels/` (likely `InfoPanel`, ~261 lines) | First consumer that justifies the `useSQLEditorContext` → Pinia bridge. |
+| **3** | Remaining read-only data panels (`Tables`, `Views`, `Functions`, `Procedures`, `Triggers`, `Sequences`, `Packages`, `ExternalTables`, `Diagram`) | Same shape as Stage 2 — repeat the pattern. |
+| **4** | `EditorCommon` chrome (chooser dropdowns, share popover, save modal, action bar) | Replace surrounding chrome before touching Monaco. |
+| **5** | `AsidePanel` sub-panes (`HistoryPane`, `AccessPane`, `WorksheetPane`, `SchemaPane`) | Largest sub-trees but each is independently shippable. |
+| **6** | `ConnectionPanel` and `TabList` | Self-contained subsystems. |
+| **7** | `EditorCommon/ResultView` (incl. `VirtualDataTable`, `SingleResultViewV1`, `DetailPanel`) | Heaviest interior — depends on table virtualization story being settled. |
+| **8** | Monaco wrapper (`SQLEditor.vue`, `CompactSQLEditor.vue`) | Behind a stable integration seam per playbook. |
+| **9** | `SQLEditorPage` + `SQLEditorHomePage` orchestrator → `react/pages/sql-editor/SQLEditorPage.tsx`; flip the route in `router/sqlEditor.ts`; lift `useSQLEditorContext` providers to React. | Shell flip, only after all interior leaves are React. |
+| **10** | Delete `frontend/src/views/sql-editor/` and `SQLEditorLayout.vue`; cleanup. | After `rg` confirms zero callers. |
+
+## 9. Practical checklist for Stage 1
+
+- [ ] `frontend/src/react/components/BytebaseLogo.tsx` + test created.
+- [ ] `frontend/src/react/components/sql-editor/WelcomeButton.tsx` + test created.
+- [ ] `frontend/src/react/components/sql-editor/Welcome.tsx` + test created (uses `usePermissionCheck`, accepts `onChangeConnection` prop).
+- [ ] `frontend/src/react/mount.ts` updated with `./components/sql-editor/*.tsx` glob and `"./components/sql-editor"` in `pageDirs`.
+- [ ] `EditorPanel/StandardPanel/StandardPanel.vue` swapped to `<ReactPageMount v-else page="Welcome" :on-change-connection="changeConnection" />` (line 55) and import updated (line 98). `showConnectionPanel` + `asidePanelTab` added to the existing `useSQLEditorContext()` destructure.
+- [ ] Entire Vue `EditorPanel/Welcome/` directory (`Welcome.vue`, `Button.vue`, `index.ts`) deleted after `rg "from.*EditorPanel/Welcome"` confirms no other callers.
+- [ ] React i18n keys verified to resolve.
+- [ ] `pnpm --dir frontend fix && check && type-check && test` all pass.
+- [ ] Manual UX-parity screenshots captured for all 5 permission/logo states.
diff --git a/frontend/src/react/components/BytebaseLogo.test.tsx b/frontend/src/react/components/BytebaseLogo.test.tsx
new file mode 100644
index 0000000000..cebe84dbad
--- /dev/null
+++ b/frontend/src/react/components/BytebaseLogo.test.tsx
@@ -0,0 +1,76 @@
+import type { ReactElement } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mocks = vi.hoisted(() => ({
+ useVueState: vi.fn<(getter: () => unknown) => unknown>(),
+}));
+
+vi.mock("@/react/hooks/useVueState", () => ({
+ useVueState: mocks.useVueState,
+}));
+
+vi.mock("@/store", () => ({
+ useWorkspaceV1Store: vi.fn(),
+}));
+
+vi.mock("@/assets/logo-full.svg", () => ({
+ default: "/assets/logo-full.svg",
+}));
+
+let BytebaseLogo: typeof import("./BytebaseLogo").BytebaseLogo;
+
+const renderIntoContainer = (element: ReactElement) => {
+ const container = document.createElement("div");
+ const root = createRoot(container);
+ return {
+ container,
+ render: () => {
+ act(() => {
+ root.render(element);
+ });
+ },
+ unmount: () =>
+ act(() => {
+ root.unmount();
+ }),
+ };
+};
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ ({ BytebaseLogo } = await import("./BytebaseLogo"));
+});
+
+describe("BytebaseLogo", () => {
+ test("renders custom workspace logo when present", () => {
+ mocks.useVueState.mockReturnValue("https://example.com/logo.png");
+ const { container, render, unmount } = renderIntoContainer(
+ <BytebaseLogo />
+ );
+ render();
+ const img = container.querySelector("img");
+ expect(img).not.toBeNull();
+ expect(img?.getAttribute("src")).toBe("https://example.com/logo.png");
+ expect(img?.getAttribute("alt")).toBe("branding logo");
+ unmount();
+ });
+
+ test("renders fallback Bytebase SVG when workspace has no custom logo", () => {
+ mocks.useVueState.mockReturnValue("");
+ const { container, render, unmount } = renderIntoContainer(
+ <BytebaseLogo />
+ );
+ render();
+ const img = container.querySelector("img");
+ expect(img).not.toBeNull();
+ expect(img?.getAttribute("src")).toBe("/assets/logo-full.svg");
+ expect(img?.getAttribute("alt")).toBe("Bytebase");
+ unmount();
+ });
+});
diff --git a/frontend/src/react/components/BytebaseLogo.tsx b/frontend/src/react/components/BytebaseLogo.tsx
new file mode 100644
index 0000000000..e7841b7cfe
--- /dev/null
+++ b/frontend/src/react/components/BytebaseLogo.tsx
@@ -0,0 +1,43 @@
+import logoFull from "@/assets/logo-full.svg";
+import { useVueState } from "@/react/hooks/useVueState";
+import { useWorkspaceV1Store } from "@/store";
+
+type Props = {
+ /** Optional route name — when set, the logo is wrapped in a link that records the visit. */
+ readonly redirect?: string;
+};
+
+/**
+ * Replaces frontend/src/components/BytebaseLogo.vue. Shows the workspace's
+ * custom logo when set, otherwise the bundled Bytebase fallback SVG.
+ *
+ * The `redirect` prop is supported for future callers. It is not used by
+ * the SQL Editor Welcome screen. Router-link behavior will be added when
+ * the first React caller needs it.
+ */
+export function BytebaseLogo(_props: Props) {
+ const workspaceStore = useWorkspaceV1Store();
+ const customLogo = useVueState(
+ () => workspaceStore.currentWorkspace?.logo ?? ""
+ );
+
+ return (
+ <div className="shrink-0 max-w-44 flex items-center overflow-hidden">
+ <span className="h-full w-full select-none flex flex-row justify-center items-center">
+ {customLogo ? (
+ <img
+ src={customLogo}
+ alt="branding logo"
+ className="h-full object-contain"
+ />
+ ) : (
+ <img
+ src={logoFull}
+ alt="Bytebase"
+ className="h-8 md:h-10 w-auto object-contain"
+ />
+ )}
+ </span>
+ </div>
+ );
+}
diff --git a/frontend/src/react/components/sql-editor/Welcome.test.tsx b/frontend/src/react/components/sql-editor/Welcome.test.tsx
new file mode 100644
index 0000000000..3e2b1b95bf
--- /dev/null
+++ b/frontend/src/react/components/sql-editor/Welcome.test.tsx
@@ -0,0 +1,167 @@
+import type { ReactElement } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const mocks = vi.hoisted(() => ({
+ useTranslation: vi.fn(() => ({ t: (key: string) => key })),
+ usePermissionCheck:
+ vi.fn<
+ (
+ perms: readonly string[],
+ project?: unknown
+ ) => [boolean, string | undefined]
+ >(),
+ useVueState: vi.fn<(getter: () => unknown) => unknown>(),
+ routerPush: vi.fn(),
+}));
+
+vi.mock("react-i18next", () => ({
+ useTranslation: mocks.useTranslation,
+}));
+
+vi.mock("@/react/components/PermissionGuard", () => ({
+ usePermissionCheck: mocks.usePermissionCheck,
+}));
+
+vi.mock("@/react/hooks/useVueState", () => ({
+ useVueState: mocks.useVueState,
+}));
+
+vi.mock("@/router", () => ({
+ router: { push: mocks.routerPush },
+}));
+
+vi.mock("@/router/dashboard/workspaceRoutes", () => ({
+ INSTANCE_ROUTE_DASHBOARD: "workspace.instance",
+}));
+
+vi.mock("@/store", () => ({
+ useSQLEditorStore: vi.fn(),
+ useProjectV1Store: vi.fn(),
+ useWorkspaceV1Store: vi.fn(),
+}));
+
+vi.mock("@/assets/logo-full.svg", () => ({
+ default: "/assets/logo-full.svg",
+}));
+
+let Welcome: typeof import("./Welcome").Welcome;
+
+const renderIntoContainer = (element: ReactElement) => {
+ const container = document.createElement("div");
+ const root = createRoot(container);
+ document.body.appendChild(container);
+ return {
+ container,
+ render: () => {
+ act(() => {
+ root.render(element);
+ });
+ },
+ unmount: () => {
+ act(() => {
+ root.unmount();
+ });
+ container.remove();
+ },
+ };
+};
+
+beforeEach(async () => {
+ vi.clearAllMocks();
+ // Default: workspace logo empty, both permissions granted.
+ mocks.useVueState.mockReturnValue("");
+ mocks.usePermissionCheck.mockReturnValue([true, undefined]);
+ ({ Welcome } = await import("./Welcome"));
+});
+
+describe("Welcome", () => {
+ test("renders both buttons when both permissions present", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ expect(container.textContent).toContain("sql-editor.add-a-new-instance");
+ expect(container.textContent).toContain("sql-editor.connect-to-a-database");
+ unmount();
+ });
+
+ test("hides Add-Instance when missing bb.instances.create", () => {
+ mocks.usePermissionCheck.mockImplementation((perms) => {
+ if (perms.includes("bb.instances.create")) return [false, "missing"];
+ return [true, undefined];
+ });
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ expect(container.textContent).not.toContain(
+ "sql-editor.add-a-new-instance"
+ );
+ expect(container.textContent).toContain("sql-editor.connect-to-a-database");
+ unmount();
+ });
+
+ test("hides Connect when missing bb.sql.select", () => {
+ mocks.usePermissionCheck.mockImplementation((perms) => {
+ if (perms.includes("bb.sql.select")) return [false, "missing"];
+ return [true, undefined];
+ });
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ expect(container.textContent).toContain("sql-editor.add-a-new-instance");
+ expect(container.textContent).not.toContain(
+ "sql-editor.connect-to-a-database"
+ );
+ unmount();
+ });
+
+ test("hides both buttons when neither permission present", () => {
+ mocks.usePermissionCheck.mockReturnValue([false, "missing"]);
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ expect(container.querySelectorAll("button")).toHaveLength(0);
+ unmount();
+ });
+
+ test("routes to instance dashboard with #add hash on Add-Instance click", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={() => {}} />
+ );
+ render();
+ const buttons = container.querySelectorAll("button");
+ // Add-Instance is the first button (matches Vue order).
+ act(() => {
+ (buttons[0] as HTMLButtonElement).click();
+ });
+ expect(mocks.routerPush).toHaveBeenCalledWith({
+ name: "workspace.instance",
+ hash: "#add",
+ });
+ unmount();
+ });
+
+ test("invokes onChangeConnection on Connect click", () => {
+ const onChangeConnection = vi.fn();
+ const { container, render, unmount } = renderIntoContainer(
+ <Welcome onChangeConnection={onChangeConnection} />
+ );
+ render();
+ const buttons = container.querySelectorAll("button");
+ // Connect is the second button (matches Vue order).
+ act(() => {
+ (buttons[1] as HTMLButtonElement).click();
+ });
+ expect(onChangeConnection).toHaveBeenCalledTimes(1);
+ unmount();
+ });
+});
diff --git a/frontend/src/react/components/sql-editor/Welcome.tsx b/frontend/src/react/components/sql-editor/Welcome.tsx
new file mode 100644
index 0000000000..4b66aad028
--- /dev/null
+++ b/frontend/src/react/components/sql-editor/Welcome.tsx
@@ -0,0 +1,69 @@
+import { LayersIcon, LinkIcon } from "lucide-react";
+import { useTranslation } from "react-i18next";
+import { BytebaseLogo } from "@/react/components/BytebaseLogo";
+import { usePermissionCheck } from "@/react/components/PermissionGuard";
+import { useVueState } from "@/react/hooks/useVueState";
+import { router } from "@/router";
+import { INSTANCE_ROUTE_DASHBOARD } from "@/router/dashboard/workspaceRoutes";
+import { useProjectV1Store, useSQLEditorStore } from "@/store";
+import { WelcomeButton } from "./WelcomeButton";
+
+export type WelcomeProps = {
+ /**
+ * Called when the user clicks "Connect to a database". Vue parent
+ * passes a callback that sets `asidePanelTab = "SCHEMA"` and
+ * `showConnectionPanel = true` on the Vue-side SQL Editor context.
+ */
+ readonly onChangeConnection: () => void;
+};
+
+export function Welcome({ onChangeConnection }: WelcomeProps) {
+ const { t } = useTranslation();
+ const sqlEditorStore = useSQLEditorStore();
+ const projectV1Store = useProjectV1Store();
+
+ const project = useVueState(() => {
+ const projectName = sqlEditorStore.project;
+ return projectName
+ ? projectV1Store.getProjectByName(projectName)
+ : undefined;
+ });
+
+ const [showCreateInstanceButton] = usePermissionCheck([
+ "bb.instances.create",
+ ]);
+ const [showConnectButton] = usePermissionCheck(["bb.sql.select"], project);
+
+ const handleCreateInstance = () => {
+ router.push({
+ name: INSTANCE_ROUTE_DASHBOARD,
+ hash: "#add",
+ });
+ };
+
+ return (
+ <div className="w-full h-full flex flex-col items-center justify-center gap-y-4">
+ <BytebaseLogo />
+ <div className="flex items-center flex-wrap gap-4">
+ {showCreateInstanceButton && (
+ <WelcomeButton
+ variant="secondary"
+ icon={<LayersIcon strokeWidth={1.5} className="size-8" />}
+ onClick={handleCreateInstance}
+ >
+ {t("sql-editor.add-a-new-instance")}
+ </WelcomeButton>
+ )}
+ {showConnectButton && (
+ <WelcomeButton
+ variant="primary"
+ icon={<LinkIcon strokeWidth={1.5} className="size-8" />}
+ onClick={onChangeConnection}
+ >
+ {t("sql-editor.connect-to-a-database")}
+ </WelcomeButton>
+ )}
+ </div>
+ </div>
+ );
+}
diff --git a/frontend/src/react/components/sql-editor/WelcomeButton.test.tsx b/frontend/src/react/components/sql-editor/WelcomeButton.test.tsx
new file mode 100644
index 0000000000..226e6fc3e2
--- /dev/null
+++ b/frontend/src/react/components/sql-editor/WelcomeButton.test.tsx
@@ -0,0 +1,87 @@
+import type { ReactElement } from "react";
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+
+(
+ globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+let WelcomeButton: typeof import("./WelcomeButton").WelcomeButton;
+
+const renderIntoContainer = (element: ReactElement) => {
+ const container = document.createElement("div");
+ const root = createRoot(container);
+ document.body.appendChild(container);
+ return {
+ container,
+ render: () => {
+ act(() => {
+ root.render(element);
+ });
+ },
+ unmount: () => {
+ act(() => {
+ root.unmount();
+ });
+ container.remove();
+ },
+ };
+};
+
+beforeEach(async () => {
+ ({ WelcomeButton } = await import("./WelcomeButton"));
+});
+
+describe("WelcomeButton", () => {
+ test("renders icon above label", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <WelcomeButton icon={<span data-testid="icon">I</span>}>
+ Hello
+ </WelcomeButton>
+ );
+ render();
+ const button = container.querySelector("button");
+ expect(button?.textContent).toContain("Hello");
+ expect(container.querySelector('[data-testid="icon"]')).not.toBeNull();
+ unmount();
+ });
+
+ test("invokes onClick when clicked", () => {
+ const handler = vi.fn();
+ const { container, render, unmount } = renderIntoContainer(
+ <WelcomeButton icon={<span>I</span>} onClick={handler}>
+ Click
+ </WelcomeButton>
+ );
+ render();
+ const button = container.querySelector("button");
+ act(() => {
+ button?.click();
+ });
+ expect(handler).toHaveBeenCalledTimes(1);
+ unmount();
+ });
+
+ test("applies primary variant classes by default", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <WelcomeButton icon={<span>I</span>}>Primary</WelcomeButton>
+ );
+ render();
+ const button = container.querySelector("button");
+ expect(button?.className).toContain("bg-accent");
+ unmount();
+ });
+
+ test("applies secondary variant classes when variant='secondary'", () => {
+ const { container, render, unmount } = renderIntoContainer(
+ <WelcomeButton icon={<span>I</span>} variant="secondary">
+ Secondary
+ </WelcomeButton>
+ );
+ render();
+ const button = container.querySelector("button");
+ expect(button?.className).toContain("border-control-border");
+ unmount();
+ });
+});
diff --git a/frontend/src/react/components/sql-editor/WelcomeButton.tsx b/frontend/src/react/components/sql-editor/WelcomeButton.tsx
new file mode 100644
index 0000000000..345a5cf911
--- /dev/null
+++ b/frontend/src/react/components/sql-editor/WelcomeButton.tsx
@@ -0,0 +1,51 @@
+import { Button as BaseButton } from "@base-ui/react/button";
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentProps, ReactNode } from "react";
+import { cn } from "@/react/lib/utils";
+
+/**
+ * Big square icon-over-label button used on the SQL Editor Welcome screen.
+ * Mirrors frontend/src/views/sql-editor/EditorPanel/Welcome/Button.vue,
+ * which wraps NButton at 7rem × 7rem with a vertical flex content slot.
+ */
+const welcomeButtonVariants = cva(
+ "inline-flex flex-col items-center justify-center gap-2 min-w-28 h-28 px-4 rounded-xs text-sm font-medium cursor-pointer transition-colors focus:outline-hidden focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50",
+ {
+ variants: {
+ variant: {
+ primary: "bg-accent text-accent-text hover:bg-accent-hover",
+ secondary:
+ "border border-control-border bg-transparent text-control hover:bg-control-bg",
+ },
+ },
+ defaultVariants: {
+ variant: "primary",
+ },
+ }
+);
+
+type WelcomeButtonProps = Omit<ComponentProps<"button">, "children"> &
+ VariantProps<typeof welcomeButtonVariants> & {
+ readonly icon: ReactNode;
+ readonly children: ReactNode;
+ };
+
+export function WelcomeButton({
+ icon,
+ children,
+ variant,
+ className,
+ ref,
+ ...props
+}: WelcomeButtonProps) {
+ return (
+ <BaseButton
+ ref={ref}
+ className={cn(welcomeButtonVariants({ variant, className }))}
+ {...props}
+ >
+ <span className="flex items-center justify-center">{icon}</span>
+ <span>{children}</span>
+ </BaseButton>
+ );
+}
diff --git a/frontend/src/react/locales/en-US.json b/frontend/src/react/locales/en-US.json
index a699f9d5df..2dd9f860a6 100644
--- a/frontend/src/react/locales/en-US.json
+++ b/frontend/src/react/locales/en-US.json
@@ -2164,6 +2164,8 @@
"access-type-unmask": "See unmasked sensitive data",
"activate-access": "Activate",
"activate-confirm": "Are you sure you want to activate this access grant?",
+ "add-a-new-instance": "Add new instance",
+ "connect-to-a-database": "Connect to database",
"expired": "Expired",
"format-sql": "Format SQL",
"grant-type-unmask": "Unmask",
diff --git a/frontend/src/react/locales/es-ES.json b/frontend/src/react/locales/es-ES.json
index edc8655a0f..d6ff429a34 100644
--- a/frontend/src/react/locales/es-ES.json
+++ b/frontend/src/react/locales/es-ES.json
@@ -2164,6 +2164,8 @@
"access-type-unmask": "See unmasked sensitive data",
"activate-access": "Activate",
"activate-confirm": "Are you sure you want to activate this access grant?",
+ "add-a-new-instance": "Agregar nueva instancia",
+ "connect-to-a-database": "Conectar a base de datos",
"expired": "Expired",
"format-sql": "Format SQL",
"grant-type-unmask": "Unmask",
diff --git a/frontend/src/react/locales/ja-JP.json b/frontend/src/react/locales/ja-JP.json
index 286c499cc6..005870807c 100644
--- a/frontend/src/react/locales/ja-JP.json
+++ b/frontend/src/react/locales/ja-JP.json
@@ -2164,6 +2164,8 @@
"access-type-unmask": "See unmasked sensitive data",
"activate-access": "Activate",
"activate-confirm": "Are you sure you want to activate this access grant?",
+ "add-a-new-instance": "新しいインスタンスを追加",
+ "connect-to-a-database": "データベースに接続",
"expired": "Expired",
"format-sql": "Format SQL",
"grant-type-unmask": "Unmask",
diff --git a/frontend/src/react/locales/vi-VN.json b/frontend/src/react/locales/vi-VN.json
index 9b65f31c63..e46c48e85d 100644
--- a/frontend/src/react/locales/vi-VN.json
+++ b/frontend/src/react/locales/vi-VN.json
@@ -2164,6 +2164,8 @@
"access-type-unmask": "See unmasked sensitive data",
"activate-access": "Activate",
"activate-confirm": "Are you sure you want to activate this access grant?",
+ "add-a-new-instance": "Thêm phiên bản mới",
+ "connect-to-a-database": "Kết nối cơ sở dữ liệu",
"expired": "Expired",
"format-sql": "Format SQL",
"grant-type-unmask": "Unmask",
diff --git a/frontend/src/react/locales/zh-CN.json b/frontend/src/react/locales/zh-CN.json
index 9ca0b0ade4..a088651b34 100644
--- a/frontend/src/react/locales/zh-CN.json
+++ b/frontend/src/react/locales/zh-CN.json
@@ -2164,6 +2164,8 @@
"access-type-unmask": "See unmasked sensitive data",
"activate-access": "激活",
"activate-confirm": "确定要激活此访问授权吗?",
+ "add-a-new-instance": "添加新实例",
+ "connect-to-a-database": "连接数据库",
"expired": "已过期",
"format-sql": "格式化 SQL",
"grant-type-unmask": "脱敏豁免",
diff --git a/frontend/src/react/mount.ts b/frontend/src/react/mount.ts
index 94f9619f81..d1b5930a58 100644
--- a/frontend/src/react/mount.ts
+++ b/frontend/src/react/mount.ts
@@ -9,12 +9,16 @@ const workspacePageLoaders = import.meta.glob("./pages/workspace/*.tsx");
const authComponentLoaders = import.meta.glob(
"./components/auth/SessionExpiredSurface.tsx"
);
+const sqlEditorComponentLoaders = import.meta.glob(
+ "./components/sql-editor/*.tsx"
+);
const pageLoaders = {
...settingsPageLoaders,
...projectPageLoaders,
...pluginComponentLoaders,
...workspacePageLoaders,
...authComponentLoaders,
+ ...sqlEditorComponentLoaders,
};
// biome-ignore lint/suspicious/noExplicitAny: React types conflict with Vue JSX in vue-tsc
@@ -55,6 +59,7 @@ const pageDirs = [
"./plugins/agent/components",
"./pages/workspace",
"./components/auth",
+ "./components/sql-editor",
];
export function resolveReactPagePath(name: string): string | undefined {
diff --git a/frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue b/frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue
index 2f2e3eca58..527bb9aa28 100644
--- a/frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue
+++ b/frontend/src/views/sql-editor/EditorPanel/StandardPanel/StandardPanel.vue
@@ -52,7 +52,12 @@
</div>
</template>
</NSplit>
- <Welcome v-else />
+ <div v-else class="flex-1 flex flex-col min-h-0">
+ <ReactPageMount
+ page="Welcome"
+ :onChangeConnection="changeConnection"
+ />
+ </div>
<ExecutingHintModal />
@@ -81,6 +86,7 @@ import { computed, defineAsyncComponent, nextTick, ref } from "vue";
import { BBSpin } from "@/bbkit";
import { useExecuteSQL } from "@/composables/useExecuteSQL";
import { AIChatToSQL } from "@/plugins/ai";
+import ReactPageMount from "@/react/ReactPageMount.vue";
import {
useConnectionOfCurrentSQLEditorTab,
useSQLEditorTabStore,
@@ -95,15 +101,24 @@ import {
} from "../../EditorCommon";
import ReadonlyModeNotSupported from "../ReadonlyModeNotSupported.vue";
import ResultPanel from "../ResultPanel";
-import Welcome from "../Welcome";
const SQLEditor = defineAsyncComponent(() => import("./SQLEditor.vue"));
const tabStore = useSQLEditorTabStore();
const { currentTab: tab, isDisconnected } = storeToRefs(tabStore);
const { instance } = useConnectionOfCurrentSQLEditorTab();
-const { showAIPanel, editorPanelSize, handleEditorPanelResize } =
- useSQLEditorContext();
+const {
+ showAIPanel,
+ editorPanelSize,
+ handleEditorPanelResize,
+ showConnectionPanel,
+ asidePanelTab,
+} = useSQLEditorContext();
+
+const changeConnection = () => {
+ asidePanelTab.value = "SCHEMA";
+ showConnectionPanel.value = true;
+};
const sqlEditorRef = ref<InstanceType<typeof SQLEditor>>();
const allowReadonlyMode = computed(() => {
diff --git a/frontend/src/views/sql-editor/EditorPanel/Welcome/Button.vue b/frontend/src/views/sql-editor/EditorPanel/Welcome/Button.vue
deleted file mode 100644
index 07488a8602..0000000000
--- a/frontend/src/views/sql-editor/EditorPanel/Welcome/Button.vue
+++ /dev/null
@@ -1,28 +0,0 @@
-<template>
- <NButton
- type="primary"
- style="--n-height: 7rem; --n-padding: 0 6px; min-width: 7rem"
- >
- <div>
- <slot name="icon" />
- </div>
- <div>
- <slot name="default" />
- </div>
- </NButton>
-</template>
-
-<script setup lang="ts">
-import { NButton } from "naive-ui";
-</script>
-
-<style scoped lang="postcss">
-:deep(.n-button__content) {
- display: flex;
- flex-direction: column;
- height: 100%;
- justify-content: center;
- align-items: center;
- gap: 0.5rem;
-}
-</style>
diff --git a/frontend/src/views/sql-editor/EditorPanel/Welcome/Welcome.vue b/frontend/src/views/sql-editor/EditorPanel/Welcome/Welcome.vue
deleted file mode 100644
index f2087b73c4..0000000000
--- a/frontend/src/views/sql-editor/EditorPanel/Welcome/Welcome.vue
+++ /dev/null
@@ -1,77 +0,0 @@
-<template>
- <div
- class="w-full flex-1 flex flex-col items-center justify-center gap-y-4"
- >
- <BytebaseLogo />
-
- <div
- class="flex items-center flex-wrap gap-4"
- >
- <Button
- v-if="showCreateInstanceButton"
- type="default"
- class="px-4!"
- @click="gotoInstanceCreatePage"
- >
- <template #icon>
- <LayersIcon :stroke-width="1.5" class="w-8 h-8" />
- </template>
- {{ $t("sql-editor.add-a-new-instance") }}
- </Button>
- <Button
- v-if="showConnectButton"
- secondary
- type="primary"
- class="px-4!"
- @click="changeConnection"
- >
- <template #icon>
- <LinkIcon :stroke-width="1.5" class="w-8 h-8" />
- </template>
- {{ $t("sql-editor.connect-to-a-database") }}
- </Button>
- </div>
- </div>
-</template>
-
-<script setup lang="ts">
-import { LayersIcon, LinkIcon } from "lucide-vue-next";
-import { storeToRefs } from "pinia";
-import { computed } from "vue";
-import { useRouter } from "vue-router";
-import BytebaseLogo from "@/components/BytebaseLogo.vue";
-import { INSTANCE_ROUTE_DASHBOARD } from "@/router/dashboard/workspaceRoutes";
-import { useProjectV1Store, useSQLEditorStore } from "@/store";
-import { hasProjectPermissionV2, hasWorkspacePermissionV2 } from "@/utils";
-import { useSQLEditorContext } from "../../context";
-import Button from "./Button.vue";
-
-const { showConnectionPanel, asidePanelTab } = useSQLEditorContext();
-const router = useRouter();
-const projectStore = useProjectV1Store();
-const { project: projectName } = storeToRefs(useSQLEditorStore());
-
-const project = computed(() =>
- projectStore.getProjectByName(projectName.value)
-);
-
-const showCreateInstanceButton = computed(() => {
- return hasWorkspacePermissionV2("bb.instances.create");
-});
-
-const showConnectButton = computed(() =>
- hasProjectPermissionV2(project.value, "bb.sql.select")
-);
-
-const changeConnection = () => {
- asidePanelTab.value = "SCHEMA";
- showConnectionPanel.value = true;
-};
-
-const gotoInstanceCreatePage = () => {
- router.push({
- name: INSTANCE_ROUTE_DASHBOARD,
- hash: `#add`,
- });
-};
-</script>
diff --git a/frontend/src/views/sql-editor/EditorPanel/Welcome/index.ts b/frontend/src/views/sql-editor/EditorPanel/Welcome/index.ts
deleted file mode 100644
index 409be99934..0000000000
--- a/frontend/src/views/sql-editor/EditorPanel/Welcome/index.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import Welcome from "./Welcome.vue";
-
-export default Welcome;