@rainbow-oh/yee-c 0.2.0 → 0.3.0

package/src/Tour/demo/indicators.tsx

@@ -0,0 +1,63 @@
+import { Button, Space, Tour } from '@rainbow-oh/yee-c';
+import React, { useRef, useState } from 'react';
+
+export default () => {
+  const [open, setOpen] = useState(false);
+  const aRef = useRef<HTMLDivElement>(null);
+  const bRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <Space direction="vertical">
+      <Space>
+        <div ref={aRef} style={{ display: 'inline-block' }}>
+          <Button>导入</Button>
+        </div>
+        <div ref={bRef} style={{ display: 'inline-block' }}>
+          <Button>筛选</Button>
+        </div>
+        <Button type="primary" onClick={() => setOpen(true)}>
+          开始
+        </Button>
+      </Space>
+
+      <Tour
+        open={open}
+        onClose={() => setOpen(false)}
+        onFinish={() => setOpen(false)}
+        indicatorsRender={(current, total) => (
+          <>
+            {Array.from({ length: total }).map((_, i) => (
+              <span
+                key={i}
+                style={{
+                  display: 'inline-block',
+                  width: 8,
+                  height: 8,
+                  marginInlineEnd: 4,
+                  borderRadius: '50%',
+                  background:
+                    i === current
+                      ? 'var(--yee-primary-color)'
+                      : 'var(--yee-border-color)',
+                  transition: 'background 0.2s',
+                }}
+              />
+            ))}
+          </>
+        )}
+        steps={[
+          {
+            target: () => aRef.current,
+            title: '导入',
+            description: '点击此处导入数据文件。',
+          },
+          {
+            target: () => bRef.current,
+            title: '筛选',
+            description: '在这里筛选你需要的数据。',
+          },
+        ]}
+      />
+    </Space>
+  );
+};

package/src/Tour/demo/placement.tsx

@@ -0,0 +1,55 @@
+import { Button, Space, Tour } from '@rainbow-oh/yee-c';
+import React, { useRef, useState } from 'react';
+
+const placements = ['top', 'right', 'bottom', 'left'] as const;
+type P = (typeof placements)[number];
+
+export default () => {
+  const [open, setOpen] = useState(false);
+  const [p, setP] = useState<P>('top');
+  const targetRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <Space direction="vertical">
+      <Space>
+        {placements.map((pl) => (
+          <Button
+            key={pl}
+            type={p === pl ? 'primary' : 'default'}
+            onClick={() => {
+              setP(pl);
+              setOpen(true);
+            }}
+          >
+            {pl}
+          </Button>
+        ))}
+      </Space>
+
+      <div
+        ref={targetRef}
+        style={{
+          display: 'inline-block',
+          padding: '16px 24px',
+          border: '1px dashed var(--yee-border-color)',
+          borderRadius: 6,
+        }}
+      >
+        目标元素
+      </div>
+
+      <Tour
+        open={open}
+        placement={p}
+        onClose={() => setOpen(false)}
+        steps={[
+          {
+            target: () => targetRef.current,
+            title: `placement: ${p}`,
+            description: '气泡卡片相对目标元素的位置；靠近视口边缘时会自动翻转。',
+          },
+        ]}
+      />
+    </Space>
+  );
+};

package/src/Tour/demo/scroll.tsx

@@ -0,0 +1,49 @@
+import { Button, Space, Tour } from '@rainbow-oh/yee-c';
+import React, { useRef, useState } from 'react';
+
+export default () => {
+  const [open, setOpen] = useState(false);
+  const farRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <Space direction="vertical" style={{ width: '100%' }}>
+      <Button type="primary" onClick={() => setOpen(true)}>
+        开始引导（自动滚动定位）
+      </Button>
+
+      <div
+        style={{
+          height: 600,
+          padding: 24,
+          background: 'var(--yee-color-bg-layout)',
+          borderRadius: 8,
+          color: '#999',
+        }}
+      >
+        ↓ 目标在下方，切换步骤时引导会自动滚动定位
+      </div>
+
+      <div ref={farRef} style={{ display: 'inline-block' }}>
+        <Button>远处的目标</Button>
+      </div>
+
+      <Tour
+        open={open}
+        onClose={() => setOpen(false)}
+        onFinish={() => setOpen(false)}
+        steps={[
+          {
+            target: () => farRef.current,
+            title: '滚动定位',
+            description: '切换到这一步时，目标会自动滚动到视口内。',
+          },
+          {
+            target: '#tour-nonexistent-target',
+            title: '目标不存在',
+            description: '找不到目标元素时，卡片居中显示（无高亮）。',
+          },
+        ]}
+      />
+    </Space>
+  );
+};

package/src/Tour/index.en-US.md

@@ -0,0 +1,61 @@
+---
+category: Components
+title: Tour
+subtitle: Tour
+group:
+  title: Feedback
+  order: 29
+toc: 'content'
+---
+
+# Tour
+
+Step-by-step guided tour: full-screen mask + highlighted target element + attached explanation card, with multi-step navigation, progress indicators, and automatic scroll-into-view. Commonly used for feature walkthroughs and new-user onboarding.
+
+## Code Demo
+
+<code src="./demo/basic.tsx" title="Basic" description="Multi-step tour, controlled open, with previous/next/finish/skip"></code>
+<code src="./demo/placement.tsx" title="Placement" description="Card placement relative to the target; auto-flips near viewport edges"></code>
+<code src="./demo/indicators.tsx" title="Custom Indicators" description="Customize step indicators via indicatorsRender"></code>
+<code src="./demo/scroll.tsx" title="Scroll & Fallback" description="Auto scroll-into-view on step change; centered card when target is missing"></code>
+
+## API
+
+### TourProps
+
+| Property | Type | Description | Default |
+| --- | --- | --- | --- |
+| open | `boolean` | Whether the tour is visible (controlled) | - |
+| steps | `TourStep[]` | Tour steps | - |
+| current | `number` | Controlled current step index | - |
+| defaultCurrent | `number` | Default current step index | `0` |
+| onClose | `() => void` | Callback when closed / skipped | - |
+| onFinish | `() => void` | Callback when all steps are finished | - |
+| onChange | `(current: number) => void` | Callback when current step changes | - |
+| placement | `Placement` | Default card placement | `'bottom'` |
+| arrow | `boolean` | Whether to show the card arrow | - |
+| mask | `boolean` | Whether to show the mask (highlight cutout + click lock) | `true` |
+| closable | `boolean` | Whether the top-right close button is shown | `true` |
+| closeIcon | `React.ReactNode` | Custom close icon | - |
+| maskClosable | `boolean` | Whether clicking the mask closes the tour | `false` |
+| indicatorsRender | `(current: number, total: number) => React.ReactNode` | Custom step indicators | default `current+1 / total` |
+| scrollIntoViewOptions | `boolean \| ScrollIntoViewOptions` | Options for target.scrollIntoView on each step | `true` |
+| className / style | | Custom root class/style | - |
+| classNames / styles | `Partial<Record<'highlight' \| 'content' \| 'header' \| 'body' \| 'footer', …>>` | Semantic structure class/style | - |
+
+> `Placement` = `'top' \| 'right' \| 'bottom' \| 'left' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'leftTop' \| 'leftBottom' \| 'rightTop' \| 'rightBottom'`, same as `Trigger`.
+
+### TourStep
+
+| Property | Type | Description | Default |
+| --- | --- | --- | --- |
+| target | `(() => HTMLElement \| null) \| string \| HTMLElement` | Highlight target (finder function / CSS selector / element) | - |
+| title | `React.ReactNode` | Card title | - |
+| description | `React.ReactNode` | Card description | - |
+| placement | `Placement` | Card placement for this step, overrides TourProps.placement | - |
+| arrow | `boolean` | Whether to show the arrow for this step | - |
+| className | `string` | Custom card class name for this step | - |
+
+### Built-in text
+
+Button labels (previous/next/finish/skip) come from `locale.tour` (`previous`/`next`/`finish`/`skip`) and follow the `ConfigProvider` locale; override via the language pack or `ConfigProvider.value.tour`.

package/src/Tour/index.ts

@@ -0,0 +1,10 @@
+import InternalTour from './tour';
+
+export type {
+  TourProps,
+  TourStep,
+  TourTarget,
+  TourSemanticDOM,
+} from './interface';
+
+export default InternalTour;

package/src/Tour/index.zh-CN.md

@@ -0,0 +1,61 @@
+---
+category: Components
+title: Tour
+subtitle: 新手引导
+group:
+  title: 反馈
+  order: 29
+toc: 'content'
+---
+
+# Tour 新手引导
+
+步骤式新手引导：全屏遮罩 + 高亮目标元素 + 贴附说明卡片，支持多步推进、进度指示、自动滚动定位。常用于产品功能向导、新用户 onboarding。
+
+## 代码演示
+
+<code src="./demo/basic.tsx" title="基础用法" description="多步引导，受控 open，支持上一步/下一步/完成/跳过"></code>
+<code src="./demo/placement.tsx" title="气泡位置" description="卡片相对目标的 placement，靠近视口边缘时自动翻转"></code>
+<code src="./demo/indicators.tsx" title="自定义进度指示" description="通过 indicatorsRender 自定义步骤进度点"></code>
+<code src="./demo/scroll.tsx" title="滚动定位与容错" description="切换步骤时自动滚动到目标；目标不存在时卡片居中"></code>
+
+## API
+
+### TourProps
+
+| 属性名 | 类型 | 描述 | 默认值 |
+| --- | --- | --- | --- |
+| open | `boolean` | 是否显示引导（受控） | - |
+| steps | `TourStep[]` | 引导步骤 | - |
+| current | `number` | 受控当前步骤索引 | - |
+| defaultCurrent | `number` | 默认当前步骤索引 | `0` |
+| onClose | `() => void` | 关闭/跳过时的回调 | - |
+| onFinish | `() => void` | 完成全部步骤时的回调 | - |
+| onChange | `(current: number) => void` | 步骤变化时的回调 | - |
+| placement | `Placement` | 卡片默认位置 | `'bottom'` |
+| arrow | `boolean` | 是否显示卡片箭头 | - |
+| mask | `boolean` | 是否显示遮罩（含高亮挖洞与点击锁定） | `true` |
+| closable | `boolean` | 是否显示右上关闭按钮 | `true` |
+| closeIcon | `React.ReactNode` | 自定义关闭图标 | - |
+| maskClosable | `boolean` | 点击遮罩是否关闭 | `false` |
+| indicatorsRender | `(current: number, total: number) => React.ReactNode` | 自定义进度指示 | 默认 `current+1 / total` |
+| scrollIntoViewOptions | `boolean \| ScrollIntoViewOptions` | 切换步骤时目标 scrollIntoView 的参数 | `true` |
+| className / style | | 自定义根类名/样式 | - |
+| classNames / styles | `Partial<Record<'highlight' \| 'content' \| 'header' \| 'body' \| 'footer', …>>` | 语义化结构类名/样式 | - |
+
+> `Placement` = `'top' \| 'right' \| 'bottom' \| 'left' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'leftTop' \| 'leftBottom' \| 'rightTop' \| 'rightBottom'`，与 `Trigger` 一致。
+
+### TourStep
+
+| 属性名 | 类型 | 描述 | 默认值 |
+| --- | --- | --- | --- |
+| target | `(() => HTMLElement \| null) \| string \| HTMLElement` | 高亮目标（查找函数 / CSS 选择器 / 元素） | - |
+| title | `React.ReactNode` | 卡片标题 | - |
+| description | `React.ReactNode` | 卡片描述 | - |
+| placement | `Placement` | 该步卡片位置，覆盖 TourProps.placement | - |
+| arrow | `boolean` | 该步是否显示箭头 | - |
+| className | `string` | 该步卡片自定义类名 | - |
+
+### 内置文案
+
+按钮（上一步/下一步/完成/跳过）与进度文案取自 `locale.tour`（`previous`/`next`/`finish`/`skip`），随 `ConfigProvider` 的 locale 切换；可通过语言包或 `ConfigProvider.value.tour` 覆盖。

package/src/Tour/interface.ts

@@ -0,0 +1,126 @@
+import type { Placement } from '../Trigger/interface';
+import type { DataAttributeProps } from '../utils/types';
+
+export type TourTarget = (() => HTMLElement | null) | string | HTMLElement;
+
+export type TourSemanticDOM =
+  | 'highlight'
+  | 'content'
+  | 'header'
+  | 'body'
+  | 'footer';
+
+export interface TourStep {
+  /**
+   * The element to highlight, supports a finder function, a CSS selector string, or an HTMLElement
+   */
+  target: TourTarget;
+  /**
+   * Card title
+   */
+  title?: React.ReactNode;
+  /**
+   * Card description
+   */
+  description?: React.ReactNode;
+  /**
+   * Card placement relative to the highlighted target
+   * @default 'bottom'
+   */
+  placement?: Placement;
+  /**
+   * Whether to show the card arrow
+   */
+  arrow?: boolean;
+  /**
+   * Custom step class name
+   */
+  className?: string;
+}
+
+export interface TourProps extends DataAttributeProps {
+  /**
+   * Custom prefix class name
+   */
+  prefixCls?: string;
+  /**
+   * Custom root class name
+   */
+  className?: string;
+  /**
+   * Custom root style
+   */
+  style?: React.CSSProperties;
+  /**
+   * Semantic structure class names
+   */
+  classNames?: Partial<Record<TourSemanticDOM, string>>;
+  /**
+   * Semantic structure styles
+   */
+  styles?: Partial<Record<TourSemanticDOM, React.CSSProperties>>;
+  /**
+   * Whether the tour is visible (controlled)
+   */
+  open: boolean;
+  /**
+   * Tour steps
+   */
+  steps: TourStep[];
+  /**
+   * Controlled current step index
+   */
+  current?: number;
+  /**
+   * Default current step index
+   */
+  defaultCurrent?: number;
+  /**
+   * Callback when the tour is closed / skipped
+   */
+  onClose?: () => void;
+  /**
+   * Callback when all steps are finished
+   */
+  onFinish?: () => void;
+  /**
+   * Callback when current step changes
+   */
+  onChange?: (current: number) => void;
+  /**
+   * Default card placement relative to the highlighted target
+   * @default 'bottom'
+   */
+  placement?: Placement;
+  /**
+   * Whether to show the card arrow by default
+   */
+  arrow?: boolean;
+  /**
+   * Whether to show the mask layer (highlight cutout + click lock)
+   * @default true
+   */
+  mask?: boolean;
+  /**
+   * Whether the close button is shown at the top-right of the card
+   * @default true
+   */
+  closable?: boolean;
+  /**
+   * Custom close icon
+   */
+  closeIcon?: React.ReactNode;
+  /**
+   * Whether clicking the mask closes the tour
+   * @default false
+   */
+  maskClosable?: boolean;
+  /**
+   * Custom step indicators renderer, receives (current, total)
+   */
+  indicatorsRender?: (current: number, total: number) => React.ReactNode;
+  /**
+   * Options passed to target.scrollIntoView on each step
+   */
+  scrollIntoViewOptions?: boolean | ScrollIntoViewOptions;
+}

package/src/Tour/style/index.less

@@ -0,0 +1,103 @@
+@pls: .yee-tour;
+
+@{pls} {
+  position: fixed;
+  inset: 0;
+  z-index: var(--yee-tour-mask-z-index);
+  pointer-events: none;
+
+  // ① click-intercept layer (box-shadow receives no pointer events, so a
+  //    transparent full-screen layer is needed to lock interaction + carry maskClosable)
+  &-mask {
+    position: absolute;
+    inset: 0;
+    pointer-events: auto;
+    background-color: transparent;
+
+    // No target to cut out → the mask itself becomes the full-screen dim layer.
+    &-full {
+      background-color: var(--yee-tour-mask-color);
+    }
+  }
+
+  // ② highlight cutout via a huge box-shadow; top/left/width/height come from
+  //    motion inline styles, position/shape/visuals from here
+  &-highlight {
+    position: fixed;
+    box-sizing: border-box;
+    border-radius: var(--yee-tour-highlight-border-radius);
+    box-shadow: 0 0 0 9999px var(--yee-tour-mask-color);
+    z-index: 1;
+    pointer-events: none;
+  }
+}
+
+// card
+.yee-tour-content {
+  position: fixed;
+  z-index: 2;
+  pointer-events: auto;
+  box-sizing: border-box;
+  width: var(--yee-tour-content-width);
+  max-width: calc(100vw - 48px);
+  padding: var(--yee-tour-content-padding);
+  background-color: var(--yee-tour-content-bg-color);
+  border-radius: var(--yee-tour-content-border-radius);
+  box-shadow: var(--yee-tour-content-box-shadow);
+
+  .yee-tour-close {
+    position: absolute;
+    top: var(--yee-tour-close-top);
+    inset-inline-end: var(--yee-tour-close-right);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    border: none;
+    background: transparent;
+    color: var(--yee-tour-close-color);
+    cursor: pointer;
+    opacity: 0.55;
+    transition: opacity var(--yee-tour-transition-duration) linear;
+
+    &:hover {
+      opacity: 1;
+    }
+  }
+
+  .yee-tour-header {
+    margin-bottom: var(--yee-tour-header-margin-bottom);
+    padding-inline-end: var(--yee-tour-close-size);
+    color: var(--yee-tour-title-color);
+    font-size: var(--yee-tour-title-font-size);
+    font-weight: var(--yee-tour-title-font-weight);
+    line-height: var(--yee-tour-title-line-height);
+  }
+
+  .yee-tour-body {
+    color: var(--yee-tour-description-color);
+    font-size: var(--yee-tour-description-font-size);
+    line-height: var(--yee-tour-description-line-height);
+  }
+
+  .yee-tour-footer {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--yee-tour-button-gap);
+    margin-top: var(--yee-tour-footer-margin-top);
+  }
+
+  .yee-tour-indicators {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--yee-tour-indicator-gap);
+  }
+
+  .yee-tour-buttons {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--yee-tour-button-gap);
+    margin-left: auto;
+  }
+}