feat: manually mirror opencoze's code from bytedance

Change-Id: I09a73aadda978ad9511264a756b2ce51f5761adf

frontend/packages/common/biz-components/src/coachmark/container/index.module.less

@@ -0,0 +1,4 @@
+.container {
+  padding: 8px;
+  background: var(--Bg-COZ-bg-max, #FFF);
+}

frontend/packages/common/biz-components/src/coachmark/container/index.tsx

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import s from './index.module.less';
+
+export const Container = ({ children }: { children: React.ReactNode }) => (
+  <div className={s.container}>{children}</div>
+);

frontend/packages/common/biz-components/src/coachmark/index.tsx

@@ -0,0 +1,172 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import Joyride, {
+  type Props,
+  ACTIONS,
+  EVENTS,
+  type CallBackProps,
+} from 'react-joyride';
+import React, { useState, useEffect, useCallback } from 'react';
+
+import { typeSafeJSONParse } from '@coze-arch/bot-utils';
+import { localStorageService } from '@coze-foundation/local-storage';
+
+import { Tooltip, type IExtraAction } from './tooltip';
+import { StepCard } from './step-card';
+
+export { type Placement, type Step } from 'react-joyride';
+
+const COACHMARK_KEY = 'coachmark';
+const COACHMARK_END = 10000;
+
+export default function Coachmark({
+  steps,
+  extraAction,
+  showProgress = true,
+  caseId,
+  itemIndex = 0,
+}: {
+  steps: Props['steps'];
+  showProgress?: Props['showProgress'];
+  extraAction?: IExtraAction;
+  caseId: string;
+  itemIndex?: number;
+}) {
+  const [visible, setVisible] = useState(false);
+  const [stepIndex, setStepIndex] = useState(itemIndex);
+
+  const initVisible = async (cid: string) => {
+    const coachMarkStorage =
+      await localStorageService.getValueSync(COACHMARK_KEY);
+    // readStep 代表已读的step index
+    const readStep = (
+      typeSafeJSONParse(coachMarkStorage) as Record<string, number> | undefined
+    )?.[cid];
+
+    // 如果没有读过，或者读过的step index 小于当前项的index，则展示。
+    const shouldShow = readStep === undefined || itemIndex > readStep;
+    setVisible(shouldShow);
+  };
+
+  // 设置已读的step index
+  const setCoachmarkReadStep = useCallback(
+    (step: number) => {
+      const coachmarkStorage =
+        localStorageService.getValue(COACHMARK_KEY) ?? '{}';
+      const coachmarkValue: Record<string, number | undefined> =
+        (typeSafeJSONParse(coachmarkStorage) ?? {}) as unknown as Record<
+          string,
+          number | undefined
+        >;
+
+      // 如果没有读过，或者要设置的index大于已读的step index 才设置，否则忽略。
+      if (
+        coachmarkValue[caseId] === undefined ||
+        step > Number(coachmarkValue[caseId])
+      ) {
+        localStorageService.setValue(
+          COACHMARK_KEY,
+          JSON.stringify({
+            ...coachmarkValue,
+            [caseId]: step,
+          }),
+        );
+      }
+    },
+    [caseId],
+  );
+
+  const handleJoyrideCallback = (data: CallBackProps) => {
+    const { action, index, type } = data;
+
+    if (
+      [EVENTS.STEP_AFTER, EVENTS.TARGET_NOT_FOUND].includes(
+        type as 'step:after' | 'error:target_not_found',
+      )
+    ) {
+      const nextIndex = index + (action === ACTIONS.PREV ? -1 : 1);
+      // 设置已经读过的step index
+      setCoachmarkReadStep(index);
+      setStepIndex(nextIndex);
+    }
+  };
+
+  useEffect(() => {
+    initVisible(caseId);
+
+    return () => {
+      setCoachmarkReadStep(itemIndex);
+    };
+  }, [caseId, setCoachmarkReadStep, itemIndex]);
+
+  return visible ? (
+    <Joyride
+      steps={steps}
+      tooltipComponent={props => (
+        <Tooltip
+          {...props}
+          extraAction={extraAction}
+          showProgress={showProgress}
+          onClose={() => {
+            setVisible(false);
+            setCoachmarkReadStep(COACHMARK_END);
+          }}
+        />
+      )}
+      continuous
+      disableOverlay
+      disableScrollParentFix
+      stepIndex={stepIndex}
+      callback={handleJoyrideCallback}
+      spotlightPadding={-6}
+      styles={{
+        options: {
+          zIndex: 100,
+          primaryColor: '#4E40E5',
+        },
+        buttonClose: {
+          display: 'none',
+        },
+        tooltip: {
+          width: 300,
+          padding: 8,
+          borderRadius: 12,
+        },
+        tooltipContent: {
+          padding: 0,
+        },
+        buttonBack: {
+          display: 'none', // 隐藏返回按钮
+        },
+      }}
+      floaterProps={{
+        styles: {
+          arrow: {
+            length: 7,
+            spread: 14,
+            margin: 40,
+          },
+          floater: {
+            filter: 'none',
+          },
+        },
+      }}
+    />
+  ) : null;
+}
+
+export { StepCard };

frontend/packages/common/biz-components/src/coachmark/step-card/index.module.less

@@ -0,0 +1,29 @@
+.title {
+  display: flex;
+  justify-content: left;
+
+  width: 100%;
+
+  font-size: 16px;
+  font-weight: 500;
+  font-style: normal;
+  color: var(--Fg-COZ-fg-plus, #060709F5);
+
+}
+
+.content {
+  width: 100%;
+  margin: 4px 0;
+
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 20px;
+  color: var(--Fg-COZ-fg-primary, #060709CC);
+  text-align: left;
+
+}
+
+.image {
+  width: 100%;
+  margin-bottom: 8px;
+}

frontend/packages/common/biz-components/src/coachmark/step-card/index.tsx

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import { Container } from '../container';
+
+import s from './index.module.less';
+
+export const StepCard = (props: {
+  content: string;
+  title: string;
+  imgSrc?: string;
+}) => {
+  const { imgSrc, content, title } = props;
+
+  return (
+    <>
+      {imgSrc ? <img className={s.image} src={imgSrc} /> : null}
+
+      <Container>
+        <div className={s.title}>{title}</div>
+        <div className={s.content}>{content}</div>
+      </Container>
+    </>
+  );
+};

frontend/packages/common/biz-components/src/coachmark/tooltip/index.module.less

@@ -0,0 +1,28 @@
+.tooltip {
+  overflow: hidden;
+
+  width: 300px;
+
+  font-size: 14px;
+
+  border-radius: 12px;
+  box-shadow: 0 16px 48px 0 #00000014, 0 8px 24px 0 #00000029;
+
+  &-footer {
+    display: flex;
+    justify-content: space-between;
+  }
+}
+
+.action-btn {
+  display: flex;
+  gap: 4px;
+
+  &-index {
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 32px;
+    color: var(--Fg-COZ-fg-secondary, rgba(6, 7, 9, 50%));
+    text-align: left;
+  }
+}

frontend/packages/common/biz-components/src/coachmark/tooltip/index.tsx

@@ -0,0 +1,133 @@
+/*
+ * Copyright 2025 coze-dev Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+ 
+import { type TooltipRenderProps, type StepMerged } from 'react-joyride';
+import { type FC, type MouseEvent, useCallback } from 'react';
+
+import { I18n } from '@coze-arch/i18n';
+import { Button } from '@coze-arch/coze-design';
+
+import { Container } from '../container';
+
+import s from './index.module.less';
+
+export interface IExtraAction {
+  content: string;
+  onClick: (step: StepMerged) => void;
+}
+
+export const Tooltip: FC<
+  TooltipRenderProps & {
+    showProgress?: boolean;
+    extraAction?: IExtraAction;
+    onClose?: () => void;
+  }
+> = props => {
+  const {
+    index,
+    isLastStep,
+    primaryProps,
+    skipProps,
+    closeProps,
+    step,
+    showProgress,
+    size,
+    extraAction,
+    onClose,
+  } = props;
+
+  const handleClose = useCallback(
+    (e: MouseEvent<HTMLElement, globalThis.MouseEvent>) => {
+      onClose?.();
+      closeProps.onClick(e);
+    },
+    [closeProps, onClose],
+  );
+
+  return (
+    <div className={s.tooltip} data-testid="coachmark_tooltip">
+      <Container>
+        {step.content}
+        <Container>
+          <div className={s['tooltip-footer']}>
+            <div className={s['action-btn-index']}>
+              {showProgress ? `${index + 1}/${size}` : ''}
+            </div>
+            <div className={s['action-btn']}>
+              {isLastStep ? (
+                extraAction ? (
+                  <>
+                    <Button
+                      size="default"
+                      color="secondary"
+                      {...closeProps}
+                      onClick={handleClose}
+                      data-testid="coachmark_tooltip_got_it"
+                    >
+                      {I18n.t('upgrade_guide_got_it')}
+                    </Button>
+                    <Button
+                      size="default"
+                      color="highlight"
+                      onClick={() => {
+                        extraAction.onClick(step);
+                        onClose?.();
+                      }}
+                    >
+                      {extraAction.content}
+                    </Button>
+                  </>
+                ) : (
+                  <Button
+                    size="default"
+                    color="highlight"
+                    {...closeProps}
+                    onClick={handleClose}
+                    data-testid="coachmark_tooltip_got_it"
+                  >
+                    {I18n.t('upgrade_guide_got_it')}
+                  </Button>
+                )
+              ) : (
+                <>
+                  <Button
+                    size="default"
+                    color={'secondary'}
+                    {...skipProps}
+                    onClick={handleClose}
+                    data-testid="coachmark_tooltip_got_it"
+                  >
+                    {I18n.t('upgrade_guide_got_it')}
+                  </Button>
+                  <Button
+                    size="default"
+                    color={'highlight'}
+                    onClick={e => {
+                      step.data?.nextAction?.();
+                      primaryProps.onClick(e);
+                    }}
+                  >
+                    {I18n.t('upgrade_guide_next')}
+                  </Button>
+                </>
+              )}
+            </div>
+          </div>
+        </Container>
+      </Container>
+    </div>
+  );
+};