Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

15.3 KB
Raw Blame
<template>
  <Teleport to="body">
    <Transition name="guide-fade">
      <div v-if="active" class="guide" role="dialog" aria-modal="true" :aria-label="stepTitle"
        @keydown.esc.prevent="dismiss" @keydown.left.prevent="prev" @keydown.right.prevent="next" tabindex="-1"
        ref="rootRef">
        <template v-if="hole">
          <div class="guide__spot" :style="spotStyle" aria-hidden="true" />
          <div v-for="(piece, i) in backdropPieces" :key="i" class="guide__backdrop guide__backdrop--hit"
            :style="piece" />
        </template>
        <div v-else class="guide__backdrop guide__backdrop--full" />

        <div v-if="hole" class="guide__ring" :style="ringStyle" aria-hidden="true" />

        <div ref="cardRef" class="guide__card" :class="{ 'guide__card--center': !hole }" :style="cardStyle">
          <button type="button" class="guide__close" :aria-label="t(`${labelsPrefix}.skip`)" @click="dismiss">
            <t-icon name="close" size="18px" />
          </button>

          <div class="guide__progress">
            <span v-for="(s, i) in steps" :key="s.key" class="guide__dot"
              :class="{ 'is-active': i === index, 'is-done': i < index }" />
          </div>

          <p class="guide__step-label">{{ t(`${labelsPrefix}.stepOf`, { current: index + 1, total: steps.length }) }}
          </p>
          <h3 class="guide__title">{{ stepTitle }}</h3>
          <p class="guide__desc">{{ stepDesc }}</p>
          <p v-if="step.interact" class="guide__interact-hint">{{ t(`${labelsPrefix}.interactHint`) }}</p>

          <div class="guide__actions">
            <button type="button" class="guide__skip" @click="dismiss">{{ t(`${labelsPrefix}.skip`) }}</button>
            <div v-if="!step.interact" class="guide__actions-main">
              <t-button v-if="index > 0" size="small" variant="outline" @click="prev">
                {{ t(`${labelsPrefix}.prev`) }}
              </t-button>
              <t-button v-if="!isLast" size="small" theme="primary" @click="next">
                {{ t(`${labelsPrefix}.next`) }}
              </t-button>
              <t-button v-else size="small" theme="primary" @click="finish">
                {{ t(`${labelsPrefix}.done`) }}
              </t-button>
            </div>
          </div>
        </div>
      </div>
    </Transition>
  </Teleport>
</template>

<script setup lang="ts">
import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
import { useI18n } from 'vue-i18n'
import type { SpotlightGuideStep } from '@/types/spotlightGuide'

const CARD_WIDTH = 340
const GAP = 16
const EDGE = 16
const PAD = 8
const holeRadius = 8
const BACKDROP_COLOR = 'rgba(15, 18, 22, 0.58)'

const props = withDefaults(
  defineProps<{
    active: boolean
    steps: SpotlightGuideStep[]
    /** i18n 前缀,步骤文案为 `${stepI18nPrefix}.${key}.title|desc` */
    stepI18nPrefix: string
    /** skip/prev/next/done/stepOf 所在前缀,默认 newUserGuide */
    labelsPrefix?: string
    /** 每步 before 执行后的等待毫秒数 */
    beforeDelayMs?: number
  }>(),
  {
    labelsPrefix: 'newUserGuide',
    beforeDelayMs: 280,
  },
)

const emit = defineEmits<{
  'update:active': [value: boolean]
  finish: []
  dismiss: []
  'step-change': [payload: { fromKey?: string; toKey: string; index: number }]
}>()

const { t } = useI18n()

const index = ref(0)
const vw = ref(window.innerWidth)
const vh = ref(window.innerHeight)
const targetRect = ref<DOMRect | null>(null)
const targetEl = ref<HTMLElement | null>(null)
const cardSize = ref({ width: CARD_WIDTH, height: 220 })

type HoleRect = { x: number; y: number; width: number; height: number }

const measureNeighborGap = (el: HTMLElement, r: DOMRect) => {
  let above = PAD
  const prev = el.previousElementSibling
  if (prev) {
    above = Math.max(0, r.top - prev.getBoundingClientRect().bottom)
  }

  let below = PAD
  const next = el.nextElementSibling
  if (next) {
    below = Math.max(0, next.getBoundingClientRect().top - r.bottom)
  } else {
    const mb = parseFloat(getComputedStyle(el).marginBottom) || 0
    below = Math.max(0, PAD - mb)
  }

  return { above, below }
}

const computeHighlightHole = (el: HTMLElement, r: DOMRect): HoleRect => {
  const { above, below } = measureNeighborGap(el, r)
  const inset = Math.min(PAD, above, below)

  let x = r.left - inset
  let y = r.top - inset
  let width = r.width + inset * 2
  let height = r.height + inset * 2

  if (x < 0) {
    width += x
    x = 0
  }
  if (y < 0) {
    height += y
    y = 0
  }
  const rightOverflow = x + width - vw.value
  if (rightOverflow > 0) {
    width -= rightOverflow
  }
  const bottomOverflow = y + height - vh.value
  if (bottomOverflow > 0) {
    height -= bottomOverflow
  }

  return { x, y, width, height }
}

const rootRef = ref<HTMLElement | null>(null)
const cardRef = ref<HTMLElement | null>(null)

let retryTimer: ReturnType<typeof setTimeout> | null = null

const step = computed(() => props.steps[index.value] ?? props.steps[0])
const isLast = computed(() => index.value === props.steps.length - 1)
const stepTitle = computed(() => t(`${props.stepI18nPrefix}.${step.value.key}.title`))
const stepDesc = computed(() => t(`${props.stepI18nPrefix}.${step.value.key}.desc`))

const hole = computed(() => {
  const el = targetEl.value
  const r = targetRect.value
  if (!el || !r) return null
  return computeHighlightHole(el, r)
})

const backdropPieces = computed(() => {
  const h = hole.value
  if (!h) return []
  const w = vw.value
  const v = vh.value
  return [
    { top: '0px', left: '0px', width: `${w}px`, height: `${h.y}px` },
    {
      top: `${h.y + h.height}px`,
      left: '0px',
      width: `${w}px`,
      height: `${Math.max(0, v - h.y - h.height)}px`,
    },
    { top: `${h.y}px`, left: '0px', width: `${h.x}px`, height: `${h.height}px` },
    {
      top: `${h.y}px`,
      left: `${h.x + h.width}px`,
      width: `${Math.max(0, w - h.x - h.width)}px`,
      height: `${h.height}px`,
    },
  ]
})

const holeFrameStyle = computed(() => {
  if (!hole.value) return {}
  return {
    left: `${hole.value.x}px`,
    top: `${hole.value.y}px`,
    width: `${hole.value.width}px`,
    height: `${hole.value.height}px`,
    borderRadius: `${holeRadius}px`,
  }
})

const spotStyle = computed(() => ({
  ...holeFrameStyle.value,
  boxShadow: `0 0 0 9999px ${BACKDROP_COLOR}`,
}))

const ringStyle = holeFrameStyle

const overlaps = (
  a: { left: number; top: number; right: number; bottom: number },
  b: { left: number; top: number; right: number; bottom: number },
) => !(a.right <= b.left || a.left >= b.right || a.bottom <= b.top || a.top >= b.bottom)

const cardStyle = computed(() => {
  const w = Math.min(CARD_WIDTH, vw.value - EDGE * 2)
  const h = cardSize.value.height
  const h0 = hole.value

  if (!h0) {
    return {
      width: `${w}px`,
      left: `${(vw.value - w) / 2}px`,
      top: `${Math.max(EDGE, vh.value * 0.32 - h / 2)}px`,
    }
  }

  const holeBox = { left: h0.x, top: h0.y, right: h0.x + h0.width, bottom: h0.y + h0.height }
  type Placement = 'right' | 'left' | 'bottom' | 'top'
  const order: Placement[] = (() => {
    const pref = step.value.placement ?? 'right'
    const all: Placement[] = ['right', 'left', 'bottom', 'top']
    return [pref, ...all.filter((p) => p !== pref)]
  })()

  const candidates: Record<Placement, { left: number; top: number }> = {
    right: { left: holeBox.right + GAP, top: h0.y + h0.height / 2 - h / 2 },
    left: { left: holeBox.left - w - GAP, top: h0.y + h0.height / 2 - h / 2 },
    bottom: { left: h0.x + h0.width / 2 - w / 2, top: holeBox.bottom + GAP },
    top: { left: h0.x + h0.width / 2 - w / 2, top: holeBox.top - h - GAP },
  }

  for (const place of order) {
    const c = candidates[place]
    const left = Math.min(Math.max(EDGE, c.left), vw.value - w - EDGE)
    const top = Math.min(Math.max(EDGE, c.top), vh.value - h - EDGE)
    const cardBox = { left, top, right: left + w, bottom: top + h }
    if (!overlaps(cardBox, holeBox)) {
      return { width: `${w}px`, left: `${left}px`, top: `${top}px` }
    }
  }

  const left = Math.min(Math.max(EDGE, (vw.value - w) / 2), vw.value - w - EDGE)
  const top = Math.min(Math.max(EDGE, holeBox.bottom + GAP), vh.value - h - EDGE)
  return { width: `${w}px`, left: `${left}px`, top: `${top}px` }
})

const queryTarget = (selector?: string): HTMLElement | null => {
  if (!selector) return null
  for (const part of selector.split(',').map((s) => s.trim()).filter(Boolean)) {
    const el = document.querySelector<HTMLElement>(part)
    if (!el) continue
    const r = el.getBoundingClientRect()
    if (r.width > 2 && r.height > 2) return el
  }
  return null
}

const measureCard = async () => {
  await nextTick()
  if (cardRef.value) {
    cardSize.value = {
      width: cardRef.value.offsetWidth,
      height: cardRef.value.offsetHeight,
    }
  }
}

const locate = async (retry = 0) => {
  vw.value = window.innerWidth
  vh.value = window.innerHeight

  const cur = step.value
  if (!cur.target) {
    targetEl.value = null
    targetRect.value = null
    await measureCard()
    return
  }

  const el = queryTarget(cur.target)
  if (!el) {
    if (retry < 12) {
      if (retryTimer) clearTimeout(retryTimer)
      retryTimer = setTimeout(() => locate(retry + 1), 120)
      return
    }
    if (cur.optional) {
      goTo(index.value + 1)
      return
    }
    targetEl.value = null
    targetRect.value = null
    await measureCard()
    return
  }

  el.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'smooth' })
  targetEl.value = el
  targetRect.value = el.getBoundingClientRect()
  await measureCard()
}

const goTo = async (i: number) => {
  if (i < 0 || i >= props.steps.length) return
  if (retryTimer) {
    clearTimeout(retryTimer)
    retryTimer = null
  }
  const fromKey = props.steps[index.value]?.key
  index.value = i
  emit('step-change', { fromKey, toKey: step.value.key, index: i })
  await step.value.before?.()
  const delay = step.value.before ? props.beforeDelayMs : 0
  if (delay > 0) {
    await new Promise((r) => setTimeout(r, delay))
  }
  await locate()
  await nextTick()
  rootRef.value?.focus()
}

const next = () => goTo(index.value + 1)
const prev = () => goTo(index.value - 1)

const close = () => {
  if (retryTimer) {
    clearTimeout(retryTimer)
    retryTimer = null
  }
  emit('update:active', false)
  targetEl.value = null
  targetRect.value = null
}

const finish = () => {
  emit('finish')
  close()
}

const dismiss = () => {
  emit('dismiss')
  finish()
}

const onViewportChange = () => {
  if (!props.active) return
  locate()
}

const open = async () => {
  index.value = 0
  emit('update:active', true)
  await nextTick()
  await goTo(0)
}

watch(
  () => props.active,
  (val, old) => {
    if (val && !old) {
      open()
    } else if (!val && old) {
      if (retryTimer) {
        clearTimeout(retryTimer)
        retryTimer = null
      }
    }
  },
)

onBeforeUnmount(() => {
  window.removeEventListener('resize', onViewportChange)
  window.removeEventListener('scroll', onViewportChange, true)
  if (retryTimer) clearTimeout(retryTimer)
})

watch(
  () => props.active,
  (val) => {
    if (val) {
      window.addEventListener('resize', onViewportChange)
      window.addEventListener('scroll', onViewportChange, true)
    } else {
      window.removeEventListener('resize', onViewportChange)
      window.removeEventListener('scroll', onViewportChange, true)
    }
  },
  { immediate: true },
)

defineExpose({ open, close })
</script>

<style lang="less" scoped>
.guide {
  position: fixed;
  inset: 0;
  z-index: 5000;
  outline: none;
  pointer-events: none;
}

.guide__backdrop {
  position: fixed;
  pointer-events: auto;
  background: rgba(15, 18, 22, 0.58);
  transition:
    top 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    left 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    width 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    height 0.28s cubic-bezier(0.4, 0, 0.2, 1);

  &--full {
    inset: 0;
  }

  &--hit {
    background: transparent;
  }
}

.guide__spot {
  position: fixed;
  box-sizing: border-box;
  pointer-events: none;
  background: transparent;
  transition:
    top 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    left 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    width 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    height 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    border-radius 0.28s cubic-bezier(0.4, 0, 0.2, 1);
}

.guide__ring {
  position: fixed;
  box-sizing: border-box;
  pointer-events: none;
  border: 2px solid var(--td-brand-color);
  box-shadow: 0 0 0 4px color-mix(in srgb, var(--td-brand-color) 18%, transparent);
  transition:
    top 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    left 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    width 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    height 0.28s cubic-bezier(0.4, 0, 0.2, 1);
}

.guide__card {
  position: fixed;
  z-index: 1;
  pointer-events: auto;
  display: flex;
  flex-direction: column;
  gap: 8px;
  padding: 18px 18px 14px;
  border-radius: 14px;
  background: var(--td-bg-color-container);
  border: 1px solid var(--td-component-stroke);
  box-shadow: 0 20px 48px rgba(0, 0, 0, 0.18);
  color: var(--td-text-color-primary);
  max-height: calc(100vh - 32px);
  overflow-y: auto;
  transition:
    top 0.28s cubic-bezier(0.4, 0, 0.2, 1),
    left 0.28s cubic-bezier(0.4, 0, 0.2, 1);

  &--center {
    max-width: calc(100vw - 32px);
  }
}

.guide__close {
  position: absolute;
  top: 10px;
  right: 10px;
  display: flex;
  align-items: center;
  justify-content: center;
  width: 28px;
  height: 28px;
  padding: 0;
  border: none;
  border-radius: var(--app-radius-md);
  background: transparent;
  color: var(--td-text-color-secondary);
  cursor: pointer;

  &:hover {
    background: var(--td-bg-color-container-hover);
    color: var(--td-text-color-primary);
  }
}

.guide__progress {
  display: flex;
  gap: 5px;
}

.guide__dot {
  width: 6px;
  height: 6px;
  border-radius: 50%;
  background: var(--td-bg-color-component);
  transition: width var(--app-motion-base) ease, background var(--app-motion-base) ease;

  &.is-active {
    width: 16px;
    border-radius: var(--app-radius-pill);
    background: var(--td-brand-color);
  }

  &.is-done {
    background: color-mix(in srgb, var(--td-brand-color) 40%, transparent);
  }
}

.guide__step-label {
  margin: 6px 0 0;
  font-size: var(--app-text-sm);
  color: var(--td-text-color-placeholder);
}

.guide__title {
  margin: 0;
  padding-right: 24px;
  font-size: var(--app-text-2xl);
  font-weight: 600;
  line-height: 26px;
}

.guide__desc {
  margin: 0;
  font-size: var(--app-text-base);
  line-height: 22px;
  color: var(--td-text-color-secondary);
}

.guide__interact-hint {
  margin: 0;
  font-size: var(--app-text-md);
  line-height: 20px;
  color: var(--td-brand-color);
  font-weight: 500;
}

.guide__actions {
  display: flex;
  align-items: center;
  justify-content: space-between;
  gap: 8px;
  margin-top: 4px;
  padding-top: 10px;
  border-top: 1px solid var(--td-component-stroke);
}

.guide__skip {
  border: none;
  background: transparent;
  padding: 0;
  font-size: var(--app-text-md);
  color: var(--td-text-color-placeholder);
  cursor: pointer;

  &:hover {
    color: var(--td-text-color-secondary);
  }
}

.guide__actions-main {
  display: flex;
  gap: 8px;
}

.guide-fade-enter-active,
.guide-fade-leave-active {
  transition: opacity var(--app-motion-base) ease;
}

.guide-fade-enter-from,
.guide-fade-leave-to {
  opacity: 0;
}

@media (max-width: 720px) {
  .guide__card {
    left: 16px !important;
    right: 16px;
    width: auto !important;
    top: auto !important;
    bottom: 16px;
    max-height: 56vh;
  }
}
</style>