The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
Add onboarding stepper component for embedding data permissions onboarding (#68801)
Phoomparin Manode1fb87ba1c0
diff --git a/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.module.css b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.module.cssnew file mode 100644index 00000000000..9b652a4c203--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.module.css@@ -0,0 +1,114 @@+/* Step root - shared styles */+.StepRoot {+ position: relative;+ border: 1px solid var(--mb-color-border);+ border-radius: 0.5rem;+ margin-bottom: 1rem;+ background-color: var(--mb-color-background-primary);+}++.StepRoot[data-active="true"] {+ padding: 4rem 4rem;+}++.StepRoot[data-active="false"] {+ padding: 1.5rem 4rem 1.5rem 2rem;+ cursor: pointer;+ transition: background-color 0.15s ease;++ &:hover {+ background-color: var(--mb-color-background-hover);+ }+}++.StepRoot[data-locked="true"] {+ cursor: not-allowed;++ &:hover {+ background-color: var(--mb-color-background-primary);+ }+}++/* Step header (title + lock icon) */+.StepHeader {+ display: flex;+ align-items: center;+ justify-content: space-between;+}++/* Step title */+.StepTitle {+ color: var(--mb-color-text-primary);+ font-weight: 700;+}++.StepRoot[data-active="true"] .StepTitle {+ font-size: 1.25rem;+}++.StepRoot[data-active="false"] .StepTitle {+ font-size: 1.0625rem;+}++.StepRoot[data-active="true"] .StepHeader {+ margin-bottom: 1rem;+}++.StepRoot[data-active="false"] .StepHeader {+ margin: 0;+}++.StepTitle[data-completed="true"] {+ color: var(--mb-color-text-secondary);+}++/* Step number (circle) */+.StepNumber {+ position: absolute;+ left: 0;+ transform: translateX(-50%);+ display: flex;+ justify-content: center;+ align-items: center;+ width: 2.625rem;+ height: 2.625rem;+ border: 1px solid var(--mb-color-border);+ border-radius: 50%;+ background-color: var(--mb-color-background-primary);+}++.StepRoot[data-active="true"] .StepNumber {+ top: 3.5rem;+}++.StepRoot[data-active="false"] .StepNumber {+ top: 50%;+ transform: translate(-50%, -50%);+}++.StepNumber[data-completed="true"] {+ background-color: var(--mb-color-background-success);+}++.StepNumberText {+ color: var(--mb-color-brand);+ font-weight: 700;+ line-height: 1;+}++.StepNumberIcon {+ width: 1rem;+ height: 1rem;+ color: var(--mb-color-success);+}++.StepLockIcon {+ width: 0.75rem;+ height: 0.75rem;+ color: var(--mb-color-text-tertiary);+}++/* Step content (only shown when active) */+.StepContent {+ margin-top: 1rem;+}diff --git a/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.stories.tsx b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.stories.tsxnew file mode 100644index 00000000000..0a4af082f66--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.stories.tsx@@ -0,0 +1,172 @@+import { useState } from "react";++import { Box, Button, Stack, Text } from "metabase/ui";++import {+ OnboardingStepper,+ type OnboardingStepperProps,+} from "./OnboardingStepper";++const args: OnboardingStepperProps = {+ completedSteps: {},+ lockedSteps: {},+ children: null,+};++const argTypes = {+ completedSteps: {+ control: { type: "object" },+ },+ lockedSteps: {+ control: { type: "object" },+ },+};++export default {+ title: "Components/OnboardingStepper",+ component: OnboardingStepper,+ args,+ argTypes,+};++const DefaultExample = () => {+ const [completedSteps, setCompletedSteps] = useState<Record<string, boolean>>(+ {+ "step-1": false,+ "step-2": false,+ "step-3": false,+ },+ );++ const markComplete = (step: string) => {+ setCompletedSteps((prev) => ({ ...prev, [step]: true }));+ };++ return (+ <Box maw={600} ml="xl">+ <OnboardingStepper completedSteps={completedSteps} lockedSteps={{}}>+ <OnboardingStepper.Step+ stepId="step-1"+ title="Connect to your database"+ >+ <Stack gap="lg">+ <Text>+ Connect your database to start exploring your data. Metabase+ supports PostgreSQL, MySQL, and many other databases.+ </Text>+ <Box>+ <Button+ variant="filled"+ onClick={() => markComplete("step-1")}+ disabled={completedSteps["step-1"]}+ >+ {completedSteps["step-1"] ? "Connected!" : "Connect database"}+ </Button>+ </Box>+ </Stack>+ </OnboardingStepper.Step>++ <OnboardingStepper.Step stepId="step-2" title="Invite your team">+ <Stack gap="lg">+ <Text>+ Invite colleagues to collaborate on dashboards and questions.+ </Text>+ <Box>+ <Button+ variant="filled"+ onClick={() => markComplete("step-2")}+ disabled={completedSteps["step-2"]}+ >+ {completedSteps["step-2"] ? "Invited!" : "Invite people"}+ </Button>+ </Box>+ </Stack>+ </OnboardingStepper.Step>++ <OnboardingStepper.Step+ stepId="step-3"+ title="Create your first dashboard"+ >+ <Stack gap="lg">+ <Text>+ Build a dashboard to visualize your data and share insights with+ your team.+ </Text>+ <Box>+ <Button+ variant="filled"+ onClick={() => markComplete("step-3")}+ disabled={completedSteps["step-3"]}+ >+ {completedSteps["step-3"]+ ? "Dashboard created!"+ : "Create dashboard"}+ </Button>+ </Box>+ </Stack>+ </OnboardingStepper.Step>+ </OnboardingStepper>+ </Box>+ );+};++export const Default = {+ render: () => <DefaultExample />,+ parameters: {+ docs: {+ description: {+ story:+ "Click the buttons to mark steps as complete. The stepper will automatically open the next incomplete step.",+ },+ },+ },+};++const LockedStepsExample = () => {+ return (+ <Box maw={600} ml="xl">+ <OnboardingStepper+ completedSteps={{ "step-1": true }}+ lockedSteps={{ "step-3": true, "step-4": true, "step-5": true }}+ >+ <OnboardingStepper.Step+ stepId="step-1"+ title="Add a database connection"+ >+ <Text>Connect your database to Metabase.</Text>+ </OnboardingStepper.Step>++ <OnboardingStepper.Step stepId="step-2" title="Configure SSO">+ <Text>Set up single sign-on for your team.</Text>+ </OnboardingStepper.Step>++ <OnboardingStepper.Step+ stepId="step-3"+ title="Select data to make available"+ >+ <Text>Choose which data to expose to your customers.</Text>+ </OnboardingStepper.Step>++ <OnboardingStepper.Step stepId="step-4" title="Create tenants">+ <Text>Set up tenants for multi-tenant embedding.</Text>+ </OnboardingStepper.Step>++ <OnboardingStepper.Step stepId="step-5" title="Summary">+ <Text>Review your setup.</Text>+ </OnboardingStepper.Step>+ </OnboardingStepper>+ </Box>+ );+};++export const LockedSteps = {+ render: () => <LockedStepsExample />,+ parameters: {+ docs: {+ description: {+ story:+ "Steps can be locked to indicate they are not yet available. A lock icon appears on the right side of locked steps.",+ },+ },+ },+};diff --git a/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.tsx b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.tsxnew file mode 100644index 00000000000..cc166cfc2b4--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.tsx@@ -0,0 +1,92 @@+import { Children, isValidElement, useEffect, useMemo, useState } from "react";++import { StepperContext } from "./OnboardingStepperContext";+import { OnboardingStepperStep } from "./OnboardingStepperStep";+import { useScrollStepIntoView } from "./hooks/use-scroll-step-into-view";+import type { OnboardingStepperProps } from "./types";++export type {+ OnboardingStepperProps,+ OnboardingStepperStepProps,+} from "./types";++/**+ * A stepper component for onboarding flows.+ *+ * Shows a vertical list of steps that can be expanded.+ *+ * Automatically advances to the next incomplete+ * step when a step is completed.+ */+const OnboardingStepperRoot = ({+ children,+ completedSteps,+ lockedSteps,+ onChange,+}: OnboardingStepperProps) => {+ // Extract step IDs and compute labels from children+ const { stepIds, stepNumbers } = useMemo(() => {+ const ids: string[] = [];+ const stepIdToNumber: Record<string, number> = {};++ Children.forEach(children, (child) => {+ if (isValidElement(child)) {+ if (child.type === OnboardingStepperStep && child.props.stepId) {+ const stepId = child.props.stepId;+ ids.push(stepId);+ stepIdToNumber[stepId] = ids.length;+ } else if (child.type !== OnboardingStepperStep) {+ console.warn(+ "OnboardingStepper: Only OnboardingStepper.Step components are allowed as children.",+ );+ }+ }+ });++ return { stepIds: ids, stepNumbers: stepIdToNumber };+ }, [children]);++ // First incomplete step will be active by default+ const defaultActiveStep = useMemo(() => {+ return stepIds.find((id) => !completedSteps[id]) ?? null;+ }, [stepIds, completedSteps]);++ const [activeStep, setActiveStepState] = useState<string | null>(+ defaultActiveStep,+ );++ const { stepRefs, scrollStepIntoView } = useScrollStepIntoView(stepIds);++ const setActiveStep = (stepId: string | null) => {+ setActiveStepState(stepId);+ scrollStepIntoView(stepId);+ onChange?.(stepId);+ };++ // Move on to next incomplete step when completedSteps changes+ useEffect(() => {+ const nextIncomplete = stepIds.find((id) => !completedSteps[id]) ?? null;++ setActiveStepState(nextIncomplete);+ scrollStepIntoView(nextIncomplete);+ }, [completedSteps, stepIds, scrollStepIntoView]);++ return (+ <StepperContext.Provider+ value={{+ activeStep,+ completedSteps,+ lockedSteps,+ stepNumbers,+ stepRefs,+ setActiveStep,+ }}+ >+ {children}+ </StepperContext.Provider>+ );+};++export const OnboardingStepper = Object.assign(OnboardingStepperRoot, {+ Step: OnboardingStepperStep,+});diff --git a/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.unit.spec.tsx b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.unit.spec.tsxnew file mode 100644index 00000000000..bc4604d9fdf--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepper.unit.spec.tsx@@ -0,0 +1,141 @@+import userEvent from "@testing-library/user-event";++import { getIcon, render, screen } from "__support__/ui";++import { OnboardingStepper } from "./OnboardingStepper";++const TestStepper = ({+ completedSteps = {},+ lockedSteps = {},+ onChange,+}: {+ completedSteps?: Record<string, boolean>;+ lockedSteps?: Record<string, boolean>;+ onChange?: (value: string | null) => void;+}) => (+ <OnboardingStepper+ completedSteps={completedSteps}+ lockedSteps={lockedSteps}+ onChange={onChange}+ >+ <OnboardingStepper.Step stepId="step-1" title="First step">+ First step content+ </OnboardingStepper.Step>++ <OnboardingStepper.Step stepId="step-2" title="Second step">+ Second step content+ </OnboardingStepper.Step>++ <OnboardingStepper.Step stepId="step-3" title="Third step">+ Third step content+ </OnboardingStepper.Step>+ </OnboardingStepper>+);++const setup = (props: Parameters<typeof TestStepper>[0] = {}) => {+ const { rerender } = render(<TestStepper {...props} />);++ return {+ rerender: (newProps: Parameters<typeof TestStepper>[0]) =>+ rerender(<TestStepper {...props} {...newProps} />),+ };+};++describe("OnboardingStepper", () => {+ it("shows all step titles by default", () => {+ setup();++ expect(screen.getByText("First step")).toBeInTheDocument();+ expect(screen.getByText("Second step")).toBeInTheDocument();+ expect(screen.getByText("Third step")).toBeInTheDocument();+ });++ it("opens the first incomplete step by default", () => {+ setup({ completedSteps: { "step-1": true } });++ // first step is completed, so second step should be active+ expect(screen.getByText("Second step content")).toBeInTheDocument();+ expect(screen.queryByText("First step content")).not.toBeInTheDocument();+ });++ it("does not open any step when all steps are completed", () => {+ setup({+ completedSteps: { "step-1": true, "step-2": true, "step-3": true },+ });++ expect(screen.queryByText("First step content")).not.toBeInTheDocument();+ expect(screen.queryByText("Second step content")).not.toBeInTheDocument();+ expect(screen.queryByText("Third step content")).not.toBeInTheDocument();+ });++ it("switches to clicked step", async () => {+ setup();++ // first step is active by default+ expect(screen.getByText("First step content")).toBeInTheDocument();++ await userEvent.click(screen.getByText("Second step"));++ expect(screen.getByText("Second step content")).toBeInTheDocument();+ expect(screen.queryByText("First step content")).not.toBeInTheDocument();+ });++ it("shows checkmark icon for completed steps", () => {+ setup({ completedSteps: { "step-1": true, "step-2": true } });++ // should have two check icons for completed steps+ const checkIcons = screen.getAllByRole("img", { name: /check/i });+ expect(checkIcons).toHaveLength(2);+ });++ it("retains completed styling when selecting a completed step", async () => {+ setup({ completedSteps: { "step-1": true } });++ await userEvent.click(screen.getByText("First step"));++ // should show content and still have check icon+ expect(screen.getByText("First step content")).toBeInTheDocument();+ expect(getIcon("check")).toBeInTheDocument();+ });++ it("move on to next incomplete step when completedSteps changes", () => {+ const { rerender } = setup();++ // first step is active by default+ expect(screen.getByText("First step content")).toBeInTheDocument();++ // mark first step as complete+ rerender({ completedSteps: { "step-1": true } });++ // should move on to second step+ expect(screen.getByText("Second step content")).toBeInTheDocument();+ expect(screen.queryByText("First step content")).not.toBeInTheDocument();+ });++ it("calls onChange when step changes", async () => {+ const onChange = jest.fn();+ setup({ onChange });++ await userEvent.click(screen.getByText("Second step"));+ expect(onChange).toHaveBeenCalledWith("step-2");+ });++ it("shows lock icon for locked steps", () => {+ setup({ lockedSteps: { "step-2": true, "step-3": true } });++ expect(screen.getAllByRole("img", { name: /lock/i })).toHaveLength(2);+ });++ it("does not expand locked steps when clicked", async () => {+ setup({ lockedSteps: { "step-2": true } });++ // first step is active by default+ expect(screen.getByText("First step content")).toBeInTheDocument();++ await userEvent.click(screen.getByText("Second step"));++ // second step is locked, so first step should still be active+ expect(screen.getByText("First step content")).toBeInTheDocument();+ expect(screen.queryByText("Second step content")).not.toBeInTheDocument();+ });+});diff --git a/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepperContext.tsx b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepperContext.tsxnew file mode 100644index 00000000000..ec544f1b7b1--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepperContext.tsx@@ -0,0 +1,14 @@+import { createContext } from "react";++import type { StepperContextValue } from "./types";++export const StepperContext = createContext<StepperContextValue>({+ activeStep: null,+ completedSteps: {},+ lockedSteps: {},+ stepNumbers: {},+ stepRefs: {},+ setActiveStep: () => {},+});++StepperContext.displayName = "StepperContext";diff --git a/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepperStep.tsx b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepperStep.tsxnew file mode 100644index 00000000000..74091356fde--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/OnboardingStepperStep.tsx@@ -0,0 +1,70 @@+import { useContext } from "react";++import { Box, Icon } from "metabase/ui";++import S from "./OnboardingStepper.module.css";+import { StepperContext } from "./OnboardingStepperContext";+import type { OnboardingStepperStepProps } from "./types";++export function OnboardingStepperStep({+ stepId,+ title,+ children,+ "data-testid": testId,+}: OnboardingStepperStepProps) {+ const {+ activeStep,+ completedSteps,+ lockedSteps,+ stepNumbers,+ stepRefs,+ setActiveStep,+ } = useContext(StepperContext);++ const ref = stepRefs[stepId];+ const isActive = activeStep === stepId;+ const isCompleted = completedSteps[stepId] ?? false;+ const isLocked = lockedSteps[stepId] ?? false;+ const stepNumber = stepNumbers[stepId] ?? 0;++ return (+ <Box+ component="section"+ ref={ref}+ className={S.StepRoot}+ role="listitem"+ aria-label={title}+ aria-current={isActive ? "step" : undefined}+ data-active={isActive}+ data-locked={isLocked}+ data-testid={testId}+ onClick={() => {+ if (isActive || isLocked) {+ return;+ }++ setActiveStep(stepId);+ }}+ >+ <div className={S.StepNumber} data-completed={isCompleted}>+ {isCompleted ? (+ <Icon name="check" className={S.StepNumberIcon} />+ ) : (+ <span className={S.StepNumberText}>{stepNumber}</span>+ )}+ </div>++ <div className={S.StepHeader}>+ <div className={S.StepTitle} data-completed={isCompleted}>+ {title}+ </div>++ {isLocked && (+ <Icon name="lock" className={S.StepLockIcon} aria-label="Locked" />+ )}+ </div>++ {isActive && <div className={S.StepContent}>{children}</div>}+ </Box>+ );+}diff --git a/frontend/src/metabase/common/components/OnboardingStepper/hooks/use-scroll-step-into-view.ts b/frontend/src/metabase/common/components/OnboardingStepper/hooks/use-scroll-step-into-view.tsnew file mode 100644index 00000000000..4c410157740--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/hooks/use-scroll-step-into-view.ts@@ -0,0 +1,38 @@+import { createRef, useCallback, useMemo } from "react";++interface UseScrollStepIntoViewResult {+ stepRefs: Record<string, React.RefObject<HTMLDivElement>>;+ scrollStepIntoView: (stepId: string | null) => void;+}++/**+ * Creates refs for each step and provides a function to scroll a step into view.+ * Used to smoothly scroll the active step into the viewport when it changes.+ */+export function useScrollStepIntoView(+ stepIds: string[],+): UseScrollStepIntoViewResult {+ const stepRefs = useMemo(() => {+ return stepIds.reduce(+ (refs, stepId) => {+ refs[stepId] = createRef<HTMLDivElement>();+ return refs;+ },+ {} as Record<string, React.RefObject<HTMLDivElement>>,+ );+ }, [stepIds]);++ const scrollStepIntoView = useCallback(+ (stepId: string | null) => {+ if (stepId && stepRefs[stepId]) {+ stepRefs[stepId].current?.scrollIntoView({+ behavior: "smooth",+ block: "center",+ });+ }+ },+ [stepRefs],+ );++ return { stepRefs, scrollStepIntoView };+}diff --git a/frontend/src/metabase/common/components/OnboardingStepper/index.ts b/frontend/src/metabase/common/components/OnboardingStepper/index.tsnew file mode 100644index 00000000000..3e642f91df5--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/index.ts@@ -0,0 +1,5 @@+export { OnboardingStepper } from "./OnboardingStepper";+export type {+ OnboardingStepperProps,+ OnboardingStepperStepProps,+} from "./types";diff --git a/frontend/src/metabase/common/components/OnboardingStepper/types.ts b/frontend/src/metabase/common/components/OnboardingStepper/types.tsnew file mode 100644index 00000000000..e86bc821424--- /dev/null+++ b/frontend/src/metabase/common/components/OnboardingStepper/types.ts@@ -0,0 +1,36 @@+import type { ReactNode } from "react";++export interface StepperContextValue {+ activeStep: string | null;+ completedSteps: Record<string, boolean>;+ lockedSteps: Record<string, boolean>;+ stepNumbers: Record<string, number>;+ stepRefs: Record<string, React.RefObject<HTMLDivElement>>;+ setActiveStep: (stepId: string | null) => void;+}++export interface OnboardingStepperProps {+ children: ReactNode;++ /** Record of step values to their completion status */+ completedSteps: Record<string, boolean>;++ /** Record of step values to their locked status */+ lockedSteps: Record<string, boolean>;++ /** Callback when the active step changes */+ onChange?: (value: string | null) => void;+}++export interface OnboardingStepperStepProps {+ /** Unique identifier for this step */+ stepId: string;++ /** Title displayed in the step header */+ title: string;++ /** Content to show when the step is active */+ children: ReactNode;++ "data-testid"?: string;+}diff --git a/frontend/src/metabase/embedding/embedding-hub/hooks/use-scroll-list-item-into-view.ts b/frontend/src/metabase/embedding/embedding-hub/hooks/use-scroll-list-item-into-view.tsdeleted file mode 100644index ff01c6b741e..00000000000--- a/frontend/src/metabase/embedding/embedding-hub/hooks/use-scroll-list-item-into-view.ts+++ /dev/null@@ -1,29 +0,0 @@-import { createRef, useCallback, useMemo } from "react";--export function useScrollListItemIntoView<K extends string>(itemIds: K[]) {- const listItemRefs = useMemo(() => {- return itemIds.reduce(- (refs, itemId) => {- refs[itemId] = createRef<HTMLDivElement>();-- return refs;- },- {} as Record<K, React.RefObject<HTMLDivElement>>,- );- }, [itemIds]);-- const isValidItem = useCallback(- (key: string | null): key is K => key != null && key in listItemRefs,- [listItemRefs],- );-- const scrollListItemIntoView = (itemId: string | null) => {- if (isValidItem(itemId)) {- const element = listItemRefs[itemId].current;-- element?.scrollIntoView({ behavior: "smooth", block: "center" });- }- };-- return { listItemRefs, scrollListItemIntoView };-}