@maple-design/cli-vue 0.0.0-stage → 1.1.0

package/site/pc/components/AppSidebar.vue

@@ -0,0 +1,144 @@
+<template>
+  <div class="maple-site-sidebar mp-elevation--3">
+    <a
+      v-for="(item, index) in menu"
+      :key="index"
+      class="maple-site-sidebar__link"
+      :href="item.type !== MenuTypes.TITLE ? `#/${language}/${item.doc}` : undefined"
+      @click.prevent="changeRoute(item)"
+    >
+      <mp-cell
+        :id="item.doc"
+        v-ripple="{
+          disabled: item.type === menuTypes.TITLE,
+        }"
+        class="maple-site-sidebar__item"
+        :class="{
+          'maple-site-sidebar__item--active': item.doc === menuName,
+          'maple-site-sidebar__cell': item.type !== menuTypes.TITLE,
+          'maple-site-sidebar__title': item.type === menuTypes.TITLE,
+          'maple-site-sidebar__cell--child': item.parent,
+        }"
+      >
+        <span class="maple-site-sidebar__indicator"></span>
+        <span v-if="item.type === menuTypes.TITLE" class="maple-site-sidebar__item--title">{{
+          item.text[language]
+        }}</span>
+        <span v-else>{{ item.text[language] }}</span>
+      </mp-cell>
+    </a>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { reactive } from 'vue'
+import { MenuTypes, type Menu } from '../../utils'
+
+const props = defineProps<{ menu: Menu[]; menuName: string; language: string }>()
+const emit = defineEmits(['change'])
+const menuTypes = reactive(MenuTypes)
+
+const changeRoute = (item: Menu) => {
+  if (item.type === MenuTypes.TITLE || props.menuName === item.doc) {
+    return
+  }
+
+  emit('change', item)
+}
+</script>
+
+<style lang="less">
+@keyframes indicator-fade-in {
+  from {
+    transform: scaleY(0);
+    opacity: 0.3;
+  }
+
+  to {
+    transform: scaleY(1);
+    opacity: 1;
+  }
+}
+
+.maple-site-sidebar {
+  padding: 0 0 15px;
+  position: sticky;
+  width: 246px;
+  height: calc(100vh - 60px - 15px);
+  top: 60px;
+  z-index: 6;
+  overflow-y: scroll;
+  box-shadow: 0 8px 12px var(--site-config-color-shadow);
+  background: var(--site-config-color-bar);
+  scrollbar-width: none;
+
+  &::-webkit-scrollbar {
+    display: none;
+  }
+
+  &__link {
+    display: block;
+    color: initial;
+    text-decoration: none;
+    &:focus-visible {
+      outline: 2px solid var(--site-config-color-link);
+      outline-offset: -2px;
+    }
+  }
+
+  &__item {
+    margin: 0 !important;
+    user-select: none !important;
+    padding: 10px 28px !important;
+
+    &--title {
+      font-size: 16px !important;
+      font-weight: 600 !important;
+      color: var(--site-config-color-text) !important;
+      line-height: 28px !important;
+      padding: 8px 0 8px !important;
+    }
+
+    &--active {
+      position: relative;
+      background: var(--site-config-color-side-bar-active-background);
+
+      span {
+        color: var(--site-config-color-side-bar);
+      }
+
+      &::before {
+        display: block;
+        content: '';
+        background: var(--site-config-color-side-bar);
+        width: 4px;
+        height: 40px;
+        position: absolute;
+        left: 0;
+        animation: indicator-fade-in 0.25s;
+      }
+    }
+  }
+
+  &__cell {
+    cursor: pointer !important;
+    font-size: 14px !important;
+    color: var(--site-config-color-text) !important;
+    transition: color 0.2s !important;
+
+    &:hover {
+      color: var(--site-config-color-side-bar) !important;
+    }
+
+    &--child {
+      padding-left: 44px !important;
+      font-size: 13px !important;
+    }
+  }
+
+  &__title {
+    margin-top: 10px !important;
+    cursor: default;
+  }
+}
+</style>

package/site/pc/components/code-example/CodeExample.spec.ts

@@ -0,0 +1,36 @@
+import { flushPromises, mount } from '@vue/test-utils'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import CodeExample from './CodeExample.vue'
+
+vi.mock('@config', () => ({
+  default: { pc: { fold: { defaultFold: true, foldHeight: 0 }, clipboard: { 'zh-CN': '已复制' } } },
+}))
+vi.mock('@maple-design/cli-vue/client', () => ({
+  getBrowserTheme: () => 'lightTheme',
+  getPCLocationInfo: () => ({ language: 'zh-CN' }),
+}))
+vi.mock('@maple-design/ui-vue', () => ({ Context: {}, Message: { success: vi.fn() } }))
+vi.mock('@maple-design/icons-vue', () => ({ IconCodeJson: 'span', IconCopy: 'span', IconXml: 'span' }))
+vi.mock('@maple-design/shared-vue', () => ({ doubleRaf: () => Promise.resolve() }))
+vi.mock('clipboard', () => ({
+  default: class {
+    on() {}
+  },
+}))
+
+afterEach(() => vi.restoreAllMocks())
+
+describe('Markdown code visibility', () => {
+  it('shows prose code with a stale folded site config and still allows manual folding', async () => {
+    vi.spyOn(HTMLElement.prototype, 'offsetHeight', 'get').mockReturnValue(160)
+    const wrapper = mount(CodeExample, { slots: { default: '<pre>npm install @maple-design/ui-vue</pre>' } })
+    const code = wrapper.get('.mp-site-code-example__code')
+    expect(code.attributes('aria-hidden')).toBe('false')
+    expect(code.attributes('style') ?? '').not.toContain('height: 0px')
+    await wrapper.get('button[aria-label="Hide Source"]').trigger('click')
+    await flushPromises()
+    expect(code.attributes('aria-hidden')).toBe('true')
+    expect(code.attributes('style')).toContain('height: 0px')
+    wrapper.unmount()
+  })
+})

package/site/pc/components/code-example/CodeExample.vue

@@ -0,0 +1,164 @@
+<template>
+  <div class="mp-site-code-example">
+    <div class="mp-site-code-example__toolbar">
+      <div class="mp-site-code-example__toolbar-group">
+        <button
+          v-if="playground"
+          type="button"
+          class="mp-site-code-example__toolbar-button"
+          aria-label="Edit In Playground"
+          data-tooltip="Edit In Playground"
+          @click="toPlayground"
+        >
+          <MIconCodeJson class="mp-site-code-example__toolbar-icon" />
+        </button>
+      </div>
+
+      <div class="mp-site-code-example__toolbar-group">
+        <button
+          v-if="clipboard"
+          :id="`clip-trigger-${cid}`"
+          :data-clipboard-target="`#clip-target-${cid}`"
+          type="button"
+          class="mp-site-code-example__toolbar-button"
+          aria-label="Copy Example Code"
+          data-tooltip="Copy Example Code"
+        >
+          <MIconCopy class="mp-site-code-example__toolbar-icon" />
+        </button>
+
+        <button
+          v-if="fold && !disabledFold"
+          type="button"
+          class="mp-site-code-example__toolbar-button"
+          :aria-controls="`clip-target-${cid}`"
+          :aria-expanded="height < 0"
+          :aria-label="height >= 0 ? 'Show Source' : 'Hide Source'"
+          :data-tooltip="height >= 0 ? 'Show Source' : 'Hide Source'"
+          @click="toggle"
+        >
+          <MIconXml class="mp-site-code-example__toolbar-icon" />
+        </button>
+      </div>
+    </div>
+    <div
+      :id="`clip-target-${cid}`"
+      ref="code"
+      class="mp-site-code-example__code"
+      :class="[disabledFold ? 'mp-site-code-example--scroller' : null]"
+      :aria-hidden="height >= 0"
+      :style="{
+        height: height >= 0 ? `${height}px` : undefined,
+      }"
+    >
+      <slot />
+    </div>
+  </div>
+</template>
+
+<script lang="ts">
+import { defineComponent, nextTick, onMounted, ref, type Ref } from 'vue'
+import config from '@config'
+import { getBrowserTheme, getPCLocationInfo } from '@maple-design/cli-vue/client'
+import { IconCodeJson as MIconCodeJson, IconCopy as MIconCopy, IconXml as MIconXml } from '@maple-design/icons-vue'
+import { doubleRaf } from '@maple-design/shared-vue'
+import { Context, Message } from '@maple-design/ui-vue'
+import Clipboard from 'clipboard'
+import { type SiteContext } from '../../../types'
+import { utoa } from '../../../utils'
+
+const context = Context as SiteContext
+
+let clipId = 0
+const offset = 10
+
+export default defineComponent({
+  components: { MIconXml, MIconCopy, MIconCodeJson },
+  name: 'MpSiteCodeExample',
+  props: {
+    // Markdown is documentation content. Keep it readable even when a running
+    // site still has an older global fold configuration.
+    defaultExpanded: {
+      type: Boolean,
+      default: true,
+    },
+    playgroundIgnore: {
+      type: Boolean,
+      default: false,
+    },
+  },
+  setup(props) {
+    const code: Ref<HTMLElement | null> = ref(null)
+    const cid: Ref<number> = ref(clipId++)
+    const fold: Ref = ref(config?.pc?.fold)
+    const disabledFold: Ref<boolean> = ref(false)
+    const clipboard: Ref = ref(config?.pc?.clipboard || {})
+    const height: Ref<number> = ref(-1)
+    const playground: Ref<string | undefined> = ref(
+      !props.playgroundIgnore ? config?.pc?.header?.playground : undefined,
+    )
+    let timer: any = null
+
+    const toggle = async () => {
+      const foldHeight = fold.value?.foldHeight ?? 0
+
+      if (height.value === foldHeight) {
+        height.value = -1
+        await nextTick()
+        const { offsetHeight } = code.value as HTMLElement
+        height.value = foldHeight
+        await doubleRaf()
+        height.value = offsetHeight
+
+        timer = setTimeout(() => {
+          height.value = -1
+        }, 250)
+      } else {
+        clearTimeout(timer)
+        const { offsetHeight } = code.value as HTMLElement
+        height.value = offsetHeight
+        await doubleRaf()
+        height.value = foldHeight
+      }
+    }
+
+    const toPlayground = () => {
+      const codeText = code.value?.innerText ?? ''
+      const file = { 'App.vue': codeText }
+      const initialTheme = getBrowserTheme('demo')
+
+      context.showPlayground = true
+      context.playgroundURL = `${playground.value}/?initialTheme=${initialTheme}#${utoa(JSON.stringify(file))}`
+    }
+
+    onMounted(() => {
+      const trigger = new Clipboard(`#clip-trigger-${cid.value}`)
+
+      trigger.on('success', () => {
+        Message.success(clipboard.value[getPCLocationInfo().language])
+      })
+
+      const { offsetHeight } = code.value as HTMLElement
+      const foldHeight = fold.value?.foldHeight ?? 0
+      disabledFold.value = offsetHeight - foldHeight < offset
+      height.value = !props.defaultExpanded && fold.value?.defaultFold && !disabledFold.value ? foldHeight : -1
+    })
+
+    return {
+      code,
+      height,
+      cid,
+      fold,
+      disabledFold,
+      clipboard,
+      playground,
+      toggle,
+      toPlayground,
+    }
+  },
+})
+</script>
+
+<style lang="less">
+@import './codeExample';
+</style>

package/site/pc/components/code-example/codeExample.less

@@ -0,0 +1,88 @@
+.mp-site-code-example {
+  margin-top: 16px;
+  margin-bottom: 4px;
+  border: thin solid var(--site-config-color-hl-border);
+  border-radius: 4px;
+  overflow: hidden;
+  transition: border 0.25s;
+
+  &__toolbar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    min-height: 40px;
+    padding: 0 5px;
+  }
+
+  &__toolbar-group {
+    display: flex;
+    align-items: center;
+  }
+
+  &__toolbar-button {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 32px;
+    height: 32px;
+    padding: 7px;
+    color: var(--site-config-color-hl-code);
+    background: transparent;
+    border: 0;
+    border-radius: 50%;
+    outline: none;
+    cursor: pointer;
+    transition: background-color 0.2s;
+
+    &:hover,
+    &:focus-visible {
+      background: color-mix(in srgb, currentColor 10%, transparent);
+    }
+
+    &::after {
+      position: absolute;
+      right: 50%;
+      bottom: calc(100% + 8px);
+      z-index: 2;
+      padding: 5px 8px;
+      color: #fff;
+      font-size: 12px;
+      line-height: 18px;
+      white-space: nowrap;
+      content: attr(data-tooltip);
+      background: rgba(0, 0, 0, 0.75);
+      border-radius: 4px;
+      opacity: 0;
+      pointer-events: none;
+      transform: translateX(50%) translateY(4px);
+      transition:
+        opacity 0.15s,
+        transform 0.15s;
+    }
+
+    &:hover::after,
+    &:focus-visible::after {
+      opacity: 1;
+      transform: translateX(50%) translateY(0);
+    }
+  }
+
+  &__toolbar-icon {
+    display: block;
+    width: 18px;
+    height: 18px;
+  }
+
+  &__code {
+    transition: all 0.25s;
+    overflow: hidden;
+    border-top: thin solid var(--site-config-color-hl-border);
+  }
+
+  &--scroller {
+    code {
+      white-space: nowrap;
+    }
+  }
+}

package/site/pc/components/code-example/index.ts

@@ -0,0 +1,10 @@
+import type { App } from 'vue'
+import CodeExample from './CodeExample.vue'
+
+CodeExample.install = function (app: App) {
+  app.component(CodeExample.name, CodeExample)
+}
+
+export const _CodeExampleComponent = CodeExample
+
+export default CodeExample

package/site/pc/components/demo-preview/DemoPreview.vue

@@ -0,0 +1,92 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import config from '@config'
+import { getBrowserTheme, getPCLocationInfo } from '@maple-design/cli-vue/client'
+import { Context, Message } from '@maple-design/ui-vue'
+import { DocPreview, type DocPreviewSource } from '@sparknest/ui-doc-preview-vue'
+import type { SiteContext } from '../../../types'
+import { utoa } from '../../../utils'
+
+const props = defineProps<{
+  sourceName: string
+  source: string
+  highlightCode: string
+}>()
+
+const context = Context as SiteContext
+const isEnglish = getPCLocationInfo().language === 'en-US'
+const sources = computed<DocPreviewSource[]>(() => [
+  {
+    name: props.sourceName,
+    rawCode: decodeURIComponent(props.source),
+    highlightCode: decodeURIComponent(props.highlightCode),
+  },
+])
+const playground =
+  typeof window !== 'undefined' && window.location.pathname.endsWith('mobile.html')
+    ? undefined
+    : config?.pc?.header?.playground
+const labels = isEnglish
+  ? {
+      playground: 'Edit in Playground',
+      copy: 'Copy source code',
+      copied: 'Source copied',
+      showSource: 'Show source',
+      hideSource: 'Hide source',
+      loadError: 'Unable to load source.',
+      retry: 'Retry',
+    }
+  : {
+      playground: '在 Playground 中编辑',
+      copy: '复制源码',
+      copied: '源码已复制',
+      showSource: '展开源码',
+      hideSource: '收起源码',
+      loadError: '源码加载失败。',
+      retry: '重试',
+    }
+
+function openPlayground(source: string) {
+  if (!playground) {
+    return
+  }
+  context.showPlayground = true
+  context.playgroundURL = `${playground}/?initialTheme=${getBrowserTheme('demo')}#${utoa(
+    JSON.stringify({ 'App.vue': source }),
+  )}`
+}
+
+function showCopiedMessage() {
+  Message.success(config?.pc?.clipboard?.[getPCLocationInfo().language] ?? labels.copied)
+}
+</script>
+
+<template>
+  <DocPreview
+    :sources="sources"
+    :show-playground="!!playground"
+    :labels="labels"
+    @copied="showCopiedMessage"
+    @playground="openPlayground"
+  >
+    <slot />
+  </DocPreview>
+</template>
+
+<style>
+.maple-component-preview {
+  margin: 24px 0;
+
+  --loca-doc-preview-bg: var(--site-config-color-bar);
+  --loca-doc-preview-example-bg: var(--site-config-color-body);
+  --loca-doc-preview-source-bg: var(--site-config-color-hl-background);
+  --loca-doc-preview-text: var(--site-config-color-text);
+  --loca-doc-preview-border: var(--site-config-color-hl-border);
+  --loca-doc-preview-brand: var(--site-config-color-text);
+}
+
+.maple-component-preview--page .loca-doc-preview__example {
+  max-height: min(620px, 70vh);
+  overflow: auto;
+}
+</style>

package/site/pc/components/demo-preview/index.ts

@@ -0,0 +1,8 @@
+import type { App } from 'vue'
+import DemoPreview from './DemoPreview.vue'
+
+DemoPreview.install = function (app: App) {
+  app.component('MpSiteDemoPreview', DemoPreview)
+}
+
+export default DemoPreview

package/site/pc/components/mobile-preview-url.ts

@@ -0,0 +1,17 @@
+export function mobilePreviewUrl(
+  base: string,
+  componentName: string,
+  language: string,
+  replace: string,
+  hash = '',
+  query: Record<string, unknown> = {},
+) {
+  const parameters = new URLSearchParams({ language, platform: 'pc', replace })
+  for (const [key, value] of Object.entries(query)) {
+    if (['language', 'platform', 'replace'].includes(key)) continue
+    for (const item of Array.isArray(value) ? value : [value]) {
+      if (item != null) parameters.append(key, String(item))
+    }
+  }
+  return `${base}#/${componentName}?${parameters}${hash ? `#${hash.replace(/^#/, '')}` : ''}`
+}

package/site/pc/components/preview-section.spec.ts

@@ -0,0 +1,24 @@
+import { afterEach, expect, it, vi } from 'vitest'
+import { currentMobileDemo } from './preview-section'
+
+afterEach(() => vi.restoreAllMocks())
+
+it('maps the current heading or group to a demo and leaves API sections unmapped', () => {
+  const root = document.createElement('main')
+  root.innerHTML =
+    '<article class="maple-site-doc"><h2>Examples</h2><div class="card"><h3>First</h3><div data-mobile-demo="first"></div></div><div class="card"><h3>Second</h3><div data-mobile-demo="second"></div></div><h2>API</h2><div class="card"><h3>Props</h3></div></article>'
+  let current = 0
+  Array.from(root.querySelectorAll('h2,h3')).forEach((heading, index) => {
+    vi.spyOn(heading, 'getBoundingClientRect').mockImplementation(
+      () => ({ top: index <= current ? 100 : 400 }) as DOMRect,
+    )
+  })
+  expect(currentMobileDemo(root)).toBe('first')
+  current = 2
+  expect(currentMobileDemo(root)).toBe('second')
+  current = 3
+  expect(currentMobileDemo(root)).toBeUndefined()
+  current = 4
+  expect(currentMobileDemo(root)).toBeUndefined()
+  expect(currentMobileDemo(null)).toBeUndefined()
+})

package/site/pc/components/preview-section.ts

@@ -0,0 +1,23 @@
+// Resolve from live geometry instead of the debounced URL hash, so switching
+// immediately after a scroll still selects the chapter currently being read.
+export function currentMobileDemo(root?: HTMLElement | null): string | undefined {
+  const headings = Array.from(
+    root?.querySelectorAll<HTMLElement>('.maple-site-doc h2, .maple-site-doc h3') ?? [],
+  ).filter((heading) => !heading.closest('.loca-doc-preview__example, details'))
+  let active = headings[0]
+  for (const heading of headings) {
+    if (heading.getBoundingClientRect().top > 120) break
+    active = heading
+  }
+  if (!active) return
+  const card = active.closest('.card')
+  if (card) return card.querySelector<HTMLElement>('[data-mobile-demo]')?.dataset.mobileDemo
+  // A group heading selects its first demo; never cross into the next group.
+  let sibling: Element | null = active
+  while (sibling) {
+    if (sibling !== active && sibling.matches('h2')) break
+    const demo = sibling.querySelector<HTMLElement>('[data-mobile-demo]')
+    if (demo) return demo.dataset.mobileDemo
+    sibling = sibling.nextElementSibling
+  }
+}