feat(react): add Tour component

.changeset/add-tour-component.md

@@ -0,0 +1,5 @@
+---
+"@tiny-design/react": minor
+---
+
+Add Tour component for step-by-step product guides with spotlight mask, Popper.js positioning, keyboard navigation, and customizable step indicators

apps/docs/src/routers.tsx

@@ -103,6 +103,7 @@ const c = {
   textLoop: ll(() => import('../../../packages/react/src/text-loop/index.md'), () => import('../../../packages/react/src/text-loop/index.zh_CN.md')),
   timeline: ll(() => import('../../../packages/react/src/timeline/index.md'), () => import('../../../packages/react/src/timeline/index.zh_CN.md')),
   tooltip: ll(() => import('../../../packages/react/src/tooltip/index.md'), () => import('../../../packages/react/src/tooltip/index.zh_CN.md')),
+  tour: ll(() => import('../../../packages/react/src/tour/index.md'), () => import('../../../packages/react/src/tour/index.zh_CN.md')),
   tree: ll(() => import('../../../packages/react/src/tree/index.md'), () => import('../../../packages/react/src/tree/index.zh_CN.md')),
   form: ll(() => import('../../../packages/react/src/form/index.md'), () => import('../../../packages/react/src/form/index.zh_CN.md')),
   cascader: ll(() => import('../../../packages/react/src/cascader/index.md'), () => import('../../../packages/react/src/cascader/index.zh_CN.md')),
@@ -300,6 +301,7 @@ export const getComponentMenu = (s: SiteLocale): RouterItem[] => {
         { title: 'Modal', route: 'modal', component: pick(c.modal, z) },
         { title: 'Notification', route: 'notification', component: pick(c.notification, z) },
         { title: 'PopConfirm', route: 'pop-confirm', component: pick(c.popConfirm, z) },
+        { title: 'Tour', route: 'tour', component: pick(c.tour, z), tag: <Tag variant='soft' color="info">New</Tag> },
         { title: 'Result', route: 'result', component: pick(c.result, z) },
         { title: 'ScrollIndicator', route: 'scroll-indicator', component: pick(c.scrollIndicator, z) },
         { title: 'Skeleton', route: 'skeleton', component: pick(c.skeleton, z) },

packages/react/src/index.ts

@@ -77,6 +77,7 @@ export { default as Textarea } from './textarea';
 export { default as Timeline } from './timeline';
 export { default as TimePicker } from './time-picker';
 export { default as Tooltip } from './tooltip';
+export { default as Tour } from './tour';
 export { default as Transfer } from './transfer';
 export { default as Transition } from './transition';
 export { default as Tree } from './tree';
@@ -92,3 +93,4 @@ export type { Locale } from './locale';
 export { useLocale } from './_utils/use-locale';
 export { useTheme } from './_utils/use-theme';
 export type { ThemeMode } from './_utils/use-theme';
+export type { TourProps, TourStepProps } from './tour';

packages/react/src/locale/en_US.ts

@@ -39,6 +39,11 @@ const en_US: Locale = {
     rgb: 'RGB',
     hsb: 'HSB',
   },
+  Tour: {
+    prevText: 'Previous',
+    nextText: 'Next',
+    finishText: 'Finish',
+  },
 };
 
 export default en_US;

packages/react/src/locale/types.ts

@@ -37,4 +37,9 @@ export type Locale = {
     rgb: string;
     hsb: string;
   };
+  Tour: {
+    prevText: string;
+    nextText: string;
+    finishText: string;
+  };
 };

packages/react/src/locale/zh_CN.ts

@@ -39,6 +39,11 @@ const zh_CN: Locale = {
     rgb: 'RGB',
     hsb: 'HSB',
   },
+  Tour: {
+    prevText: '上一步',
+    nextText: '下一步',
+    finishText: '完成',
+  },
 };
 
 export default zh_CN;

packages/react/src/style/_component.scss

@@ -74,6 +74,7 @@
 @use "../timeline/style/index" as *;
 @use "../time-picker/style/index" as *;
 @use "../tooltip/style/index" as *;
+@use "../tour/style/index" as *;
 @use "../transfer/style/index" as *;
 @use "../transition/style/index" as *;
 @use "../tree/style/index" as *;

packages/react/src/tour/__tests__/tour.test.tsx

@@ -0,0 +1,124 @@
+import React from 'react';
+import { render, fireEvent } from '@testing-library/react';
+import Tour from '../index';
+import { TourStepProps } from '../types';
+
+const steps: TourStepProps[] = [
+  { title: 'Step 1', description: 'Description 1' },
+  { title: 'Step 2', description: 'Description 2' },
+  { title: 'Step 3', description: 'Description 3' },
+];
+
+describe('<Tour />', () => {
+  it('should not render when open is false', () => {
+    const { baseElement } = render(<Tour open={false} steps={steps} />);
+    expect(baseElement.querySelector('.ty-tour')).not.toBeInTheDocument();
+  });
+
+  it('should render when open is true', () => {
+    const { getByText } = render(<Tour open steps={steps} />);
+    expect(getByText('Step 1')).toBeInTheDocument();
+    expect(getByText('Description 1')).toBeInTheDocument();
+  });
+
+  it('should render step title and description', () => {
+    const { getByText } = render(<Tour open steps={steps} />);
+    expect(getByText('Step 1')).toBeInTheDocument();
+    expect(getByText('Description 1')).toBeInTheDocument();
+  });
+
+  it('should navigate to next step', () => {
+    const onChange = jest.fn();
+    const { getByText } = render(<Tour open steps={steps} onChange={onChange} />);
+    fireEvent.click(getByText('Next'));
+    expect(onChange).toHaveBeenCalledWith(1);
+  });
+
+  it('should navigate to previous step', () => {
+    const onChange = jest.fn();
+    const { getByText } = render(<Tour open steps={steps} current={1} onChange={onChange} />);
+    fireEvent.click(getByText('Previous'));
+    expect(onChange).toHaveBeenCalledWith(0);
+  });
+
+  it('should call onClose when close button is clicked', () => {
+    const onClose = jest.fn();
+    const { baseElement } = render(<Tour open steps={steps} onClose={onClose} />);
+    const closeBtn = baseElement.querySelector('.ty-tour__close-btn') as HTMLElement;
+    fireEvent.click(closeBtn);
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('should call onFinish on last step next click', () => {
+    const onFinish = jest.fn();
+    const onClose = jest.fn();
+    const { getByText } = render(
+      <Tour open steps={steps} current={2} onFinish={onFinish} onClose={onClose} />
+    );
+    fireEvent.click(getByText('Finish'));
+    expect(onFinish).toHaveBeenCalled();
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('should render indicators', () => {
+    const { baseElement } = render(<Tour open steps={steps} />);
+    const indicators = baseElement.querySelectorAll('.ty-tour__indicator');
+    expect(indicators).toHaveLength(3);
+  });
+
+  it('should show active indicator for current step', () => {
+    const { baseElement } = render(<Tour open steps={steps} current={1} />);
+    const indicators = baseElement.querySelectorAll('.ty-tour__indicator');
+    expect(indicators[1]).toHaveClass('ty-tour__indicator_active');
+  });
+
+  it('should render mask by default', () => {
+    const { baseElement } = render(<Tour open steps={steps} />);
+    expect(baseElement.querySelector('.ty-tour__mask')).toBeInTheDocument();
+  });
+
+  it('should not render mask when mask is false', () => {
+    const { baseElement } = render(<Tour open steps={steps} mask={false} />);
+    expect(baseElement.querySelector('.ty-tour__mask')).not.toBeInTheDocument();
+  });
+
+  it('should render primary type', () => {
+    const { baseElement } = render(<Tour open steps={steps} type="primary" />);
+    expect(baseElement.querySelector('.ty-tour__panel_primary')).toBeInTheDocument();
+  });
+
+  it('should handle keyboard Escape', () => {
+    const onClose = jest.fn();
+    render(<Tour open steps={steps} onClose={onClose} />);
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(onClose).toHaveBeenCalled();
+  });
+
+  it('should center panel when no target', () => {
+    const { baseElement } = render(<Tour open steps={[{ title: 'Centered' }]} />);
+    expect(
+      baseElement.querySelector('.ty-tour__panel-wrapper_centered')
+    ).toBeInTheDocument();
+  });
+
+  it('should not render previous button on first step', () => {
+    const { queryByText } = render(<Tour open steps={steps} />);
+    expect(queryByText('Previous')).not.toBeInTheDocument();
+  });
+
+  it('should show Finish text on last step', () => {
+    const { getByText } = render(<Tour open steps={steps} current={2} />);
+    expect(getByText('Finish')).toBeInTheDocument();
+  });
+
+  it('should support custom indicatorsRender', () => {
+    const { getByText } = render(
+      <Tour
+        open
+        steps={steps}
+        indicatorsRender={(current, total) => <span>{`${current + 1}/${total}`}</span>}
+      />
+    );
+    expect(getByText('1/3')).toBeInTheDocument();
+  });
+});

packages/react/src/tour/demo/Basic.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import { Tour, Button } from '@tiny-design/react';
+import type { TourStepProps } from '../../tour/types';
+
+export default function BasicDemo() {
+  const [open, setOpen] = React.useState(false);
+  const ref1 = React.useRef<HTMLButtonElement>(null);
+  const ref2 = React.useRef<HTMLButtonElement>(null);
+  const ref3 = React.useRef<HTMLButtonElement>(null);
+
+  const steps: TourStepProps[] = [
+    {
+      title: 'Upload File',
+      description: 'Put your files here.',
+      target: () => ref1.current,
+    },
+    {
+      title: 'Save',
+      description: 'Save your changes.',
+      target: () => ref2.current,
+    },
+    {
+      title: 'Other Actions',
+      description: 'Click to see other actions.',
+      target: () => ref3.current,
+    },
+  ];
+
+  return (
+    <>
+      <div style={{ display: 'flex', gap: 16 }}>
+        <Button ref={ref1}>Upload</Button>
+        <Button ref={ref2}>Save</Button>
+        <Button ref={ref3} btnType="primary" onClick={() => setOpen(true)}>
+          Start Tour
+        </Button>
+      </div>
+      <Tour open={open} steps={steps} onClose={() => setOpen(false)} />
+    </>
+  );
+}

packages/react/src/tour/demo/Cover.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import { Tour, Button } from '@tiny-design/react';
+import type { TourStepProps } from '../../tour/types';
+
+export default function CoverDemo() {
+  const [open, setOpen] = React.useState(false);
+  const ref1 = React.useRef<HTMLButtonElement>(null);
+  const ref2 = React.useRef<HTMLButtonElement>(null);
+
+  const steps: TourStepProps[] = [
+    {
+      title: 'Create a project',
+      description: 'Start by creating a new project from the dashboard.',
+      cover: (
+        <svg viewBox="0 0 300 120" style={{ width: '100%', borderRadius: '8px 8px 0 0' }}>
+          <rect width="300" height="120" fill="#e6f4ff" />
+          <circle cx="150" cy="50" r="25" fill="#1677ff" />
+          <text x="150" y="100" textAnchor="middle" fill="#1677ff" fontSize="14">Step 1</text>
+        </svg>
+      ),
+      target: () => ref1.current,
+    },
+    {
+      title: 'Upload files',
+      description: 'Upload files to your project to get started.',
+      cover: (
+        <svg viewBox="0 0 300 120" style={{ width: '100%', borderRadius: '8px 8px 0 0' }}>
+          <rect width="300" height="120" fill="#f6ffed" />
+          <polygon points="150,25 175,75 125,75" fill="#52c41a" />
+          <text x="150" y="100" textAnchor="middle" fill="#52c41a" fontSize="14">Step 2</text>
+        </svg>
+      ),
+      target: () => ref2.current,
+    },
+  ];
+
+  return (
+    <>
+      <div style={{ display: 'flex', gap: 16 }}>
+        <Button ref={ref1}>Create</Button>
+        <Button ref={ref2} btnType="primary" onClick={() => setOpen(true)}>
+          Start Tour
+        </Button>
+      </div>
+      <Tour open={open} steps={steps} onClose={() => setOpen(false)} />
+    </>
+  );
+}

packages/react/src/tour/demo/CustomButton.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { Tour, Button } from '@tiny-design/react';
+import type { TourStepProps } from '../../tour/types';
+
+export default function CustomButtonDemo() {
+  const [open, setOpen] = React.useState(false);
+  const ref1 = React.useRef<HTMLButtonElement>(null);
+  const ref2 = React.useRef<HTMLButtonElement>(null);
+  const ref3 = React.useRef<HTMLButtonElement>(null);
+
+  const steps: TourStepProps[] = [
+    {
+      title: 'Upload File',
+      description: 'Put your files here.',
+      target: () => ref1.current,
+      nextButtonProps: { children: 'Go Next' },
+    },
+    {
+      title: 'Save',
+      description: 'Save your changes.',
+      target: () => ref2.current,
+      prevButtonProps: { children: 'Go Back' },
+      nextButtonProps: { children: 'Continue' },
+    },
+    {
+      title: 'Other Actions',
+      description: 'Click to see other actions.',
+      target: () => ref3.current,
+      prevButtonProps: { children: 'Go Back' },
+      nextButtonProps: { children: 'Done!' },
+    },
+  ];
+
+  return (
+    <>
+      <div style={{ display: 'flex', gap: 16 }}>
+        <Button ref={ref1}>Upload</Button>
+        <Button ref={ref2}>Save</Button>
+        <Button ref={ref3} btnType="primary" onClick={() => setOpen(true)}>
+          Start Tour
+        </Button>
+      </div>
+      <Tour open={open} steps={steps} onClose={() => setOpen(false)} />
+    </>
+  );
+}

packages/react/src/tour/demo/CustomIndicator.tsx

@@ -0,0 +1,48 @@
+import React from 'react';
+import { Tour, Button } from '@tiny-design/react';
+import type { TourStepProps } from '../../tour/types';
+
+export default function CustomIndicatorDemo() {
+  const [open, setOpen] = React.useState(false);
+  const ref1 = React.useRef<HTMLButtonElement>(null);
+  const ref2 = React.useRef<HTMLButtonElement>(null);
+  const ref3 = React.useRef<HTMLButtonElement>(null);
+
+  const steps: TourStepProps[] = [
+    {
+      title: 'Upload File',
+      description: 'Put your files here.',
+      target: () => ref1.current,
+    },
+    {
+      title: 'Save',
+      description: 'Save your changes.',
+      target: () => ref2.current,
+    },
+    {
+      title: 'Other Actions',
+      description: 'Click to see other actions.',
+      target: () => ref3.current,
+    },
+  ];
+
+  return (
+    <>
+      <div style={{ display: 'flex', gap: 16 }}>
+        <Button ref={ref1}>Upload</Button>
+        <Button ref={ref2}>Save</Button>
+        <Button ref={ref3} btnType="primary" onClick={() => setOpen(true)}>
+          Start Tour
+        </Button>
+      </div>
+      <Tour
+        open={open}
+        steps={steps}
+        onClose={() => setOpen(false)}
+        indicatorsRender={(current, total) => (
+          <span style={{ fontSize: 12 }}>{`${current + 1} / ${total}`}</span>
+        )}
+      />
+    </>
+  );
+}