@quantabit/onboarding-sdk 1.0.0

package/dist/index.cjs

@@ -0,0 +1,742 @@
+'use strict';
+
+var React = require('react');
+var sdkConfig = require('@quantabit/sdk-config');
+
+function OnboardingFlow({
+  steps = [],
+  onComplete,
+  onSkip,
+  className = ''
+}) {
+  const [current, setCurrent] = React.useState(0);
+  const step = steps[current];
+  if (!step) return null;
+  return /*#__PURE__*/React.createElement("div", {
+    className: `qob-flow ${className}`,
+    style: {
+      textAlign: 'center',
+      padding: 40,
+      maxWidth: 480,
+      margin: '0 auto'
+    }
+  }, step.image && /*#__PURE__*/React.createElement("img", {
+    src: step.image,
+    alt: "",
+    style: {
+      maxWidth: 240,
+      height: 'auto',
+      marginBottom: 24
+    }
+  }), step.icon && /*#__PURE__*/React.createElement("div", {
+    style: {
+      fontSize: 56,
+      marginBottom: 16
+    }
+  }, step.icon), /*#__PURE__*/React.createElement("h2", {
+    style: {
+      fontSize: 24,
+      fontWeight: 800,
+      color: '#18181b',
+      margin: '0 0 8px'
+    }
+  }, step.title), /*#__PURE__*/React.createElement("p", {
+    style: {
+      fontSize: 14,
+      color: '#71717a',
+      lineHeight: 1.6,
+      margin: '0 0 32px'
+    }
+  }, step.description), /*#__PURE__*/React.createElement("div", {
+    style: {
+      display: 'flex',
+      gap: 6,
+      justifyContent: 'center',
+      marginBottom: 24
+    }
+  }, steps.map((_, i) => /*#__PURE__*/React.createElement("div", {
+    key: i,
+    style: {
+      width: i === current ? 24 : 8,
+      height: 8,
+      borderRadius: 4,
+      background: i === current ? '#3b82f6' : i < current ? '#93c5fd' : '#e4e4e7',
+      transition: 'all 0.3s'
+    }
+  }))), /*#__PURE__*/React.createElement("div", {
+    style: {
+      display: 'flex',
+      gap: 12,
+      justifyContent: 'center'
+    }
+  }, onSkip && current < steps.length - 1 && /*#__PURE__*/React.createElement("button", {
+    onClick: onSkip,
+    style: {
+      padding: '10px 24px',
+      borderRadius: 10,
+      border: 'none',
+      background: 'transparent',
+      color: '#71717a',
+      fontSize: 14,
+      cursor: 'pointer'
+    }
+  }, "Skip"), /*#__PURE__*/React.createElement("button", {
+    onClick: () => {
+      if (current < steps.length - 1) setCurrent(c => c + 1);else onComplete?.();
+    },
+    style: {
+      padding: '10px 32px',
+      borderRadius: 10,
+      border: 'none',
+      background: '#3b82f6',
+      color: '#fff',
+      fontSize: 14,
+      fontWeight: 700,
+      cursor: 'pointer',
+      transition: 'all 0.2s'
+    }
+  }, current === steps.length - 1 ? 'Get Started' : 'Next')));
+}
+
+function SpotlightTour({
+  steps = [],
+  active = false,
+  onComplete,
+  onSkip
+}) {
+  const [current, setCurrent] = React.useState(0);
+  const step = steps[current];
+  const [rect, setRect] = React.useState(null);
+  const updateRect = React.useCallback(() => {
+    if (!step?.target) return;
+    const el = document.querySelector(step.target);
+    if (el) {
+      const r = el.getBoundingClientRect();
+      setRect({
+        top: r.top - 4,
+        left: r.left - 4,
+        width: r.width + 8,
+        height: r.height + 8
+      });
+    }
+  }, [step]);
+  React.useEffect(() => {
+    if (active) {
+      updateRect();
+      window.addEventListener('resize', updateRect);
+      return () => window.removeEventListener('resize', updateRect);
+    }
+  }, [active, updateRect]);
+  if (!active || !step || !rect) return null;
+  return /*#__PURE__*/React.createElement(React.Fragment, null, /*#__PURE__*/React.createElement("div", {
+    style: {
+      position: 'fixed',
+      inset: 0,
+      zIndex: 99998
+    }
+  }, /*#__PURE__*/React.createElement("svg", {
+    width: "100%",
+    height: "100%",
+    style: {
+      position: 'absolute'
+    }
+  }, /*#__PURE__*/React.createElement("defs", null, /*#__PURE__*/React.createElement("mask", {
+    id: "qob-mask"
+  }, /*#__PURE__*/React.createElement("rect", {
+    width: "100%",
+    height: "100%",
+    fill: "white"
+  }), /*#__PURE__*/React.createElement("rect", {
+    x: rect.left,
+    y: rect.top,
+    width: rect.width,
+    height: rect.height,
+    rx: "8",
+    fill: "black"
+  }))), /*#__PURE__*/React.createElement("rect", {
+    width: "100%",
+    height: "100%",
+    fill: "rgba(0,0,0,0.5)",
+    mask: "url(#qob-mask)"
+  }))), /*#__PURE__*/React.createElement("div", {
+    style: {
+      position: 'fixed',
+      zIndex: 99999,
+      top: rect.top + rect.height + 12,
+      left: Math.max(16, Math.min(rect.left, window.innerWidth - 320)),
+      width: 300,
+      padding: 20,
+      borderRadius: 14,
+      background: '#fff',
+      boxShadow: '0 16px 48px rgba(0,0,0,0.15)',
+      animation: 'qob-pop 0.2s ease-out'
+    }
+  }, /*#__PURE__*/React.createElement("div", {
+    style: {
+      fontSize: 12,
+      color: '#a1a1aa',
+      marginBottom: 4
+    }
+  }, "Step ", current + 1, " of ", steps.length), /*#__PURE__*/React.createElement("h4", {
+    style: {
+      fontSize: 15,
+      fontWeight: 700,
+      color: '#18181b',
+      margin: '0 0 6px'
+    }
+  }, step.title), /*#__PURE__*/React.createElement("p", {
+    style: {
+      fontSize: 13,
+      color: '#71717a',
+      margin: '0 0 16px',
+      lineHeight: 1.5
+    }
+  }, step.description), /*#__PURE__*/React.createElement("div", {
+    style: {
+      display: 'flex',
+      justifyContent: 'space-between'
+    }
+  }, onSkip && /*#__PURE__*/React.createElement("button", {
+    onClick: onSkip,
+    style: {
+      border: 'none',
+      background: 'none',
+      color: '#a1a1aa',
+      fontSize: 12,
+      cursor: 'pointer'
+    }
+  }, "Skip tour"), /*#__PURE__*/React.createElement("button", {
+    onClick: () => {
+      if (current < steps.length - 1) setCurrent(c => c + 1);else {
+        onComplete?.();
+        setCurrent(0);
+      }
+    },
+    style: {
+      padding: '6px 16px',
+      borderRadius: 6,
+      border: 'none',
+      background: '#3b82f6',
+      color: '#fff',
+      fontSize: 12,
+      fontWeight: 600,
+      cursor: 'pointer',
+      marginLeft: 'auto'
+    }
+  }, current === steps.length - 1 ? 'Finish' : 'Next'))));
+}
+
+function FeatureHighlight({
+  title,
+  description,
+  isNew = false,
+  onDismiss,
+  position = 'top-right',
+  className = ''
+}) {
+  const [visible, setVisible] = React.useState(true);
+  if (!visible) return null;
+  const dismiss = () => {
+    setVisible(false);
+    onDismiss?.();
+  };
+  return /*#__PURE__*/React.createElement("div", {
+    className: `qob-highlight ${className}`,
+    style: {
+      position: 'relative',
+      display: 'inline-block'
+    }
+  }, /*#__PURE__*/React.createElement("div", {
+    style: {
+      position: 'absolute',
+      ...(position === 'top-right' ? {
+        top: -8,
+        right: -8
+      } : position === 'top-left' ? {
+        top: -8,
+        left: -8
+      } : {
+        bottom: -8,
+        right: -8
+      }),
+      zIndex: 10
+    }
+  }, isNew && /*#__PURE__*/React.createElement("span", {
+    style: {
+      background: '#ef4444',
+      color: '#fff',
+      fontSize: 10,
+      fontWeight: 700,
+      padding: '1px 6px',
+      borderRadius: 4,
+      animation: 'qob-pulse 2s infinite'
+    }
+  }, "NEW")), /*#__PURE__*/React.createElement("div", {
+    className: "qob-tooltip",
+    style: {
+      position: 'absolute',
+      top: 'calc(100% + 8px)',
+      left: '50%',
+      transform: 'translateX(-50%)',
+      padding: '12px 16px',
+      borderRadius: 10,
+      background: '#18181b',
+      color: '#fff',
+      fontSize: 12,
+      width: 200,
+      zIndex: 100,
+      boxShadow: '0 8px 24px rgba(0,0,0,0.2)',
+      animation: 'qob-pop 0.2s ease-out'
+    }
+  }, /*#__PURE__*/React.createElement("div", {
+    style: {
+      fontWeight: 600,
+      marginBottom: 4
+    }
+  }, title), /*#__PURE__*/React.createElement("div", {
+    style: {
+      opacity: 0.8,
+      lineHeight: 1.4
+    }
+  }, description), /*#__PURE__*/React.createElement("button", {
+    onClick: dismiss,
+    style: {
+      border: 'none',
+      background: 'rgba(255,255,255,0.15)',
+      color: '#fff',
+      padding: '3px 10px',
+      borderRadius: 4,
+      fontSize: 11,
+      cursor: 'pointer',
+      marginTop: 8
+    }
+  }, "Got it")));
+}
+
+function WelcomeScreen({
+  title = 'Welcome!',
+  subtitle,
+  features = [],
+  cta = 'Get Started',
+  onAction,
+  logo,
+  className = ''
+}) {
+  return /*#__PURE__*/React.createElement("div", {
+    className: `qob-welcome ${className}`,
+    style: {
+      textAlign: 'center',
+      padding: '48px 32px',
+      maxWidth: 560,
+      margin: '0 auto'
+    }
+  }, logo && /*#__PURE__*/React.createElement("div", {
+    style: {
+      marginBottom: 20
+    }
+  }, typeof logo === 'string' ? /*#__PURE__*/React.createElement("img", {
+    src: logo,
+    alt: "",
+    style: {
+      height: 48
+    }
+  }) : logo), /*#__PURE__*/React.createElement("h1", {
+    style: {
+      fontSize: 32,
+      fontWeight: 800,
+      color: '#18181b',
+      margin: '0 0 8px'
+    }
+  }, title), subtitle && /*#__PURE__*/React.createElement("p", {
+    style: {
+      fontSize: 16,
+      color: '#71717a',
+      margin: '0 0 32px',
+      lineHeight: 1.6
+    }
+  }, subtitle), features.length > 0 && /*#__PURE__*/React.createElement("div", {
+    style: {
+      display: 'grid',
+      gridTemplateColumns: 'repeat(auto-fit,minmax(140px,1fr))',
+      gap: 16,
+      marginBottom: 32,
+      textAlign: 'center'
+    }
+  }, features.map((f, i) => /*#__PURE__*/React.createElement("div", {
+    key: i,
+    style: {
+      padding: 16,
+      borderRadius: 12,
+      border: '1px solid #f4f4f5'
+    }
+  }, /*#__PURE__*/React.createElement("div", {
+    style: {
+      fontSize: 28,
+      marginBottom: 8
+    }
+  }, f.icon), /*#__PURE__*/React.createElement("div", {
+    style: {
+      fontSize: 13,
+      fontWeight: 600,
+      color: '#18181b'
+    }
+  }, f.title), f.description && /*#__PURE__*/React.createElement("div", {
+    style: {
+      fontSize: 11,
+      color: '#71717a',
+      marginTop: 4
+    }
+  }, f.description)))), /*#__PURE__*/React.createElement("button", {
+    onClick: onAction,
+    style: {
+      padding: '14px 40px',
+      borderRadius: 12,
+      border: 'none',
+      background: '#3b82f6',
+      color: '#fff',
+      fontSize: 16,
+      fontWeight: 700,
+      cursor: 'pointer',
+      transition: 'all 0.2s'
+    }
+  }, cta));
+}
+
+const SUPPORTED_LANGUAGES = ['en', 'zh', 'ja', 'ko'];
+const messages = {
+  en: {
+    'ob.next': 'Next',
+    'ob.skip': 'Skip',
+    'ob.done': 'Get Started',
+    'ob.welcome': 'Welcome!'
+  },
+  zh: {
+    'ob.next': '下一步',
+    'ob.skip': '跳过',
+    'ob.done': '开始使用',
+    'ob.welcome': '欢迎!'
+  },
+  ja: {
+    'ob.next': '次へ',
+    'ob.skip': 'スキップ',
+    'ob.done': 'はじめる',
+    'ob.welcome': 'ようこそ!'
+  },
+  ko: {
+    'ob.next': '다음',
+    'ob.skip': '건너뛰기',
+    'ob.done': '시작하기',
+    'ob.welcome': '환영합니다!'
+  }
+};
+let currentLang = 'en';
+function setLanguage(l) {
+  if (SUPPORTED_LANGUAGES.includes(l)) currentLang = l;
+}
+function getLanguage() {
+  return currentLang;
+}
+function t(k, params = {}) {
+  let text = messages[currentLang]?.[k] || messages.en?.[k] || k;
+  Object.entries(params).forEach(([key, val]) => {
+    text = text.replace(new RegExp(`\\{${key}\\}`, 'g'), val);
+  });
+  return text;
+}
+
+function Tooltip({
+  title,
+  content,
+  placement = 'bottom',
+  onNext,
+  onSkip,
+  isLast
+}) {
+  return /*#__PURE__*/React.createElement("div", {
+    className: `onboarding-tooltip placement-${placement}`
+  }, /*#__PURE__*/React.createElement("h4", null, title), /*#__PURE__*/React.createElement("p", null, content), /*#__PURE__*/React.createElement("div", {
+    className: "onboarding-tooltip-actions"
+  }, /*#__PURE__*/React.createElement("button", {
+    className: "onboarding-btn text",
+    onClick: onSkip
+  }, t('skip')), /*#__PURE__*/React.createElement("button", {
+    className: "onboarding-btn primary",
+    onClick: onNext
+  }, isLast ? t('done') : t('next'))));
+}
+function CoachMark({
+  target,
+  children
+}) {
+  return /*#__PURE__*/React.createElement("div", {
+    className: "onboarding-coach-mark"
+  }, /*#__PURE__*/React.createElement("div", {
+    className: "onboarding-spotlight"
+  }), children);
+}
+function StepIndicator({
+  total,
+  current
+}) {
+  return /*#__PURE__*/React.createElement("div", {
+    className: "onboarding-step-indicator"
+  }, Array.from({
+    length: total
+  }, (_, i) => /*#__PURE__*/React.createElement("span", {
+    key: i,
+    className: `step-dot ${i === current ? 'active' : ''} ${i < current ? 'completed' : ''}`
+  })));
+}
+function TutorialOverlay({
+  tutorial,
+  currentStep,
+  onNext,
+  onPrev,
+  onSkip
+}) {
+  if (!tutorial) return null;
+  const step = tutorial.steps[currentStep];
+  const isFirst = currentStep === 0;
+  const isLast = currentStep === tutorial.steps.length - 1;
+  return /*#__PURE__*/React.createElement("div", {
+    className: "onboarding-overlay"
+  }, /*#__PURE__*/React.createElement("div", {
+    className: "onboarding-modal"
+  }, /*#__PURE__*/React.createElement("h3", null, step.title), /*#__PURE__*/React.createElement("p", null, step.content), /*#__PURE__*/React.createElement(StepIndicator, {
+    total: tutorial.steps.length,
+    current: currentStep
+  }), /*#__PURE__*/React.createElement("div", {
+    className: "onboarding-modal-actions"
+  }, !isFirst && /*#__PURE__*/React.createElement("button", {
+    className: "onboarding-btn secondary",
+    onClick: onPrev
+  }, t('prev')), /*#__PURE__*/React.createElement("button", {
+    className: "onboarding-btn text",
+    onClick: onSkip
+  }, t('skip')), /*#__PURE__*/React.createElement("button", {
+    className: "onboarding-btn primary",
+    onClick: onNext
+  }, isLast ? t('done') : t('next')))));
+}
+
+/**
+ * Onboarding SDK - 类型定义
+ */
+
+const StepType = {
+  HIGHLIGHT: 'highlight',
+  MODAL: 'modal',
+  TOOLTIP: 'tooltip',
+  COACH_MARK: 'coach_mark'
+};
+const TutorialStatus = {
+  NOT_STARTED: 'not_started',
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  SKIPPED: 'skipped'
+};
+function createDefaultStep() {
+  return {
+    id: '',
+    type: StepType.TOOLTIP,
+    title: '',
+    content: '',
+    target: null,
+    placement: 'bottom',
+    order: 0,
+    action: null
+  };
+}
+function createDefaultTutorial() {
+  return {
+    id: '',
+    name: '',
+    description: '',
+    steps: [],
+    status: TutorialStatus.NOT_STARTED,
+    currentStep: 0
+  };
+}
+
+/**
+ * Onboarding SDK - API 客户端
+ * 新手引导系统后端接口封装
+ * 
+ * 使用 BaseApiClient 基类，代码从 ~100 行简化到 ~70 行
+ */
+
+
+/**
+ * 新手引导 API 客户端
+ */
+class OnboardingApiClient extends sdkConfig.BaseApiClient {
+  constructor(config = {}) {
+    // 只需传入模块路径，所有配置自动处理
+    super('/onboarding', config);
+  }
+
+  // ============ 教程管理 ============
+
+  /**
+   * 获取教程列表
+   */
+  async getTutorials() {
+    return this.get('/tutorials');
+  }
+
+  /**
+   * 获取教程详情
+   * @param {string} tutorialId - 教程 ID
+   */
+  async getTutorial(tutorialId) {
+    return this.get(`/tutorials/${tutorialId}`);
+  }
+
+  /**
+   * 开始教程
+   * @param {string} tutorialId - 教程 ID
+   */
+  async startTutorial(tutorialId) {
+    return this.post(`/tutorials/${tutorialId}/start`);
+  }
+
+  /**
+   * 完成教程步骤
+   * @param {string} tutorialId - 教程 ID
+   * @param {string} stepId - 步骤 ID
+   */
+  async completeStep(tutorialId, stepId) {
+    return this.post(`/tutorials/${tutorialId}/steps/${stepId}/complete`);
+  }
+
+  /**
+   * 跳过教程
+   * @param {string} tutorialId - 教程 ID
+   */
+  async skipTutorial(tutorialId) {
+    return this.post(`/tutorials/${tutorialId}/skip`);
+  }
+
+  /**
+   * 获取整体进度
+   */
+  async getProgress() {
+    return this.get('/progress');
+  }
+
+  /**
+   * 重置教程进度
+   * @param {string} tutorialId - 教程 ID（可选，不传则重置全部）
+   */
+  async resetProgress(tutorialId = null) {
+    const endpoint = tutorialId ? `/tutorials/${tutorialId}/reset` : '/progress/reset';
+    return this.post(endpoint);
+  }
+
+  /**
+   * 获取推荐教程
+   */
+  async getRecommendedTutorials() {
+    return this.get('/tutorials/recommended');
+  }
+
+  /**
+   * 标记提示已读
+   * @param {string} tipId - 提示 ID
+   */
+  async dismissTip(tipId) {
+    return this.post(`/tips/${tipId}/dismiss`);
+  }
+
+  /**
+   * 获取新功能引导
+   */
+  async getNewFeatures() {
+    return this.get('/features/new');
+  }
+
+  /**
+   * 标记新功能已查看
+   * @param {string} featureId - 功能 ID
+   */
+  async markFeatureSeen(featureId) {
+    return this.post(`/features/${featureId}/seen`);
+  }
+}
+
+// 创建默认实例
+const onboardingApi = new OnboardingApiClient();
+
+/**
+ * Onboarding SDK - React Hooks
+ */
+function useTutorials() {
+  const [tutorials, setTutorials] = React.useState([]);
+  const [loading, setLoading] = React.useState(true);
+  React.useEffect(() => {
+    onboardingApi.getTutorials().then(setTutorials).finally(() => setLoading(false));
+  }, []);
+  return {
+    tutorials,
+    loading
+  };
+}
+function useTutorial(id) {
+  const [tutorial, setTutorial] = React.useState(null);
+  const [currentStep, setCurrentStep] = React.useState(0);
+  const [loading, setLoading] = React.useState(true);
+  React.useEffect(() => {
+    if (id) onboardingApi.getTutorial(id).then(setTutorial).finally(() => setLoading(false));
+  }, [id]);
+  const nextStep = React.useCallback(() => {
+    if (tutorial && currentStep < tutorial.steps.length - 1) {
+      onboardingApi.completeStep(id, tutorial.steps[currentStep].id);
+      setCurrentStep(s => s + 1);
+    }
+  }, [id, tutorial, currentStep]);
+  const prevStep = React.useCallback(() => setCurrentStep(s => Math.max(0, s - 1)), []);
+  const skip = React.useCallback(() => onboardingApi.skipTutorial(id), [id]);
+  return {
+    tutorial,
+    currentStep,
+    nextStep,
+    prevStep,
+    skip,
+    loading
+  };
+}
+function useOnboardingProgress() {
+  const [progress, setProgress] = React.useState(null);
+  const [loading, setLoading] = React.useState(true);
+  React.useEffect(() => {
+    onboardingApi.getProgress().then(setProgress).finally(() => setLoading(false));
+  }, []);
+  return {
+    progress,
+    loading
+  };
+}
+
+exports.CoachMark = CoachMark;
+exports.FeatureHighlight = FeatureHighlight;
+exports.OnboardingApiClient = OnboardingApiClient;
+exports.OnboardingFlow = OnboardingFlow;
+exports.SUPPORTED_LANGUAGES = SUPPORTED_LANGUAGES;
+exports.SpotlightTour = SpotlightTour;
+exports.StepIndicator = StepIndicator;
+exports.StepType = StepType;
+exports.Tooltip = Tooltip;
+exports.TutorialOverlay = TutorialOverlay;
+exports.TutorialStatus = TutorialStatus;
+exports.WelcomeScreen = WelcomeScreen;
+exports.createDefaultStep = createDefaultStep;
+exports.createDefaultTutorial = createDefaultTutorial;
+exports.getLanguage = getLanguage;
+exports.messages = messages;
+exports.onboardingApi = onboardingApi;
+exports.setLanguage = setLanguage;
+exports.t = t;
+exports.useOnboardingProgress = useOnboardingProgress;
+exports.useTutorial = useTutorial;
+exports.useTutorials = useTutorials;
+//# sourceMappingURL=index.cjs.map