apptify 0.5.1 → 0.6.0

package/templates/playground/{playground → src}/components/UserMenu.vue

@@ -1,19 +1,19 @@
 <template>
   <apple-popover v-model="opened" label="用户菜单" align="end" :width="280" panel-class="user-popup">
     <template #activator>
-      <apple-button class="user-trigger user-account-trigger" variant="ghost" icon-only label="打开用户菜单" title="用户菜单"><UserRound :size="20" /></apple-button>
+      <apple-link as="button" class="user-trigger user-account-trigger" icon-only label="打开用户菜单" title="用户菜单"><UserRound :size="20" /></apple-link>
     </template>
     <div class="user-summary">
       <apple-avatar name="林初" :size="48" />
       <div><strong>林初 <small>演示账户</small></strong><span>lin.chu@example.com</span></div>
     </div>
     <div class="user-menu-list">
-      <apple-button variant="ghost" @click="showProfile"><UserRound :size="17" /><span>个人资料</span><ArrowUpRight :size="14" aria-hidden="true" /></apple-button>
+      <apple-link as="button" @click="showProfile"><UserRound :size="17" /><span>个人资料</span><ArrowUpRight :size="14" aria-hidden="true" /></apple-link>
       <router-link to="/settings" @click="opened = false"><Settings2 :size="17" /><span>偏好设置</span><ArrowUpRight :size="14" aria-hidden="true" /></router-link>
     </div>
     <div class="user-menu-list user-menu-examples">
-      <apple-button variant="ghost" @click="openAuth('login')"><LogIn :size="17" /><span>登录 <small>Login</small></span><em>示例</em></apple-button>
-      <apple-button variant="ghost" @click="openAuth('register')"><UserPlus :size="17" /><span>注册 <small>Register</small></span><em>示例</em></apple-button>
+      <apple-link as="button" @click="openAuth('login')"><LogIn :size="17" /><span>登录 <small>Login</small></span><em>示例</em></apple-link>
+      <apple-link as="button" @click="openAuth('register')"><UserPlus :size="17" /><span>注册 <small>Register</small></span><em>示例</em></apple-link>
     </div>
   </apple-popover>
   <apple-dialog v-model="authOpen" class="user-auth-dialog" :width="560" :title="authMode === 'login' ? '登录示例' : '注册示例'" :show-footer="false" @after-close="password = ''">
@@ -34,12 +34,12 @@
         <apple-input v-model="password" label="密码" type="password" :autocomplete="authMode === 'login' ? 'current-password' : 'new-password'" required>
           <template #prefix><LockKeyhole :size="18" aria-hidden="true" /></template>
         </apple-input>
-        <apple-button v-if="authMode === 'login'" class="user-auth-forgot" variant="ghost" size="small" @click="showAuthEntry('forgot')">忘记密码？</apple-button>
+        <apple-link as="button" v-if="authMode === 'login'" class="user-auth-forgot" @click="showAuthEntry('forgot')">忘记密码？</apple-link>
       </div>
       <p class="user-auth-note">这是表单交互示例，尚未接入账户服务。填写内容不会提交到服务器。</p>
       <div class="user-auth-actions">
-        <apple-button class="user-auth-submit" type="submit" size="large">{{ authMode === 'login' ? '体验登录' : '体验注册' }}</apple-button>
-        <apple-button class="user-auth-email" variant="outline" size="large" @click="showAuthEntry('email')">邮箱验证码登录</apple-button>
+        <apple-button class="user-auth-submit" type="submit">{{ authMode === 'login' ? '体验登录' : '体验注册' }}</apple-button>
+        <apple-button class="user-auth-email" variant="outline" @click="showAuthEntry('email')">邮箱验证码登录</apple-button>
       </div>
     </apple-form>
     <div class="user-auth-alternatives">
@@ -99,10 +99,10 @@ function showProfile() {
 
 <style>
 .user-popup.apple-popover { border-radius: 24px; background: var(--apple-surface); -webkit-backdrop-filter: none; backdrop-filter: none; }
-.user-popup .user-menu-list > .apple-button > .apple-button__content { width: 100%; justify-content: flex-start; gap: 11px; }
-.user-popup .user-menu-list > .apple-button { min-height: 44px; font-weight: 400; line-height: inherit; }
-.user-popup .user-menu-list > .apple-button:hover:where(:not([data-apple-touch] *)):not(:disabled) { background: var(--apple-hover); color: var(--apple-text); }
-.user-popup .user-menu-list > .apple-button:active:not(:disabled) { background: var(--apple-pressed); color: var(--apple-text); }
+.user-popup .user-menu-list > .apple-link > .apple-link__content { width: 100%; justify-content: flex-start; gap: 11px; }
+.user-popup .user-menu-list > .apple-link { min-height: 44px; font-weight: 400; line-height: inherit; }
+.user-popup .user-menu-list > .apple-link:hover:where(:not([data-apple-touch] *)):not(:disabled) { background: var(--apple-hover); }
+.user-popup .user-menu-list > .apple-link:active:not(:disabled) { background: var(--apple-pressed); }
 .user-trigger.user-account-trigger { width: 44px; height: 44px; border: 0; background: transparent; }
 .user-trigger.user-account-trigger:focus-visible { outline: 3px solid var(--apple-accent); outline-offset: 2px; }
 .user-auth-dialog.apple-modal { border-radius: 24px; background: var(--apple-surface); -webkit-backdrop-filter: none; backdrop-filter: none; }

package/templates/playground/src/editor/AppleInputExample.vue

@@ -0,0 +1,78 @@
+<script>
+import { AppleInput, AppleTextarea, AppleLink } from 'apptify'
+import { Mail } from 'lucide-vue-next'
+
+export default {
+  components: { AppleInput, AppleTextarea, AppleLink, Mail },
+  data() {
+    return { value: 'Apptify', events: [], eventId: 0 }
+  },
+  computed: {
+    eventLog() {
+      return this.events.map(event => `${event.id}. ${event.name} ${event.value === undefined ? '无参数' : JSON.stringify(event.value)}`).join('\n')
+    },
+  },
+  watch: {
+    eventLog() {
+      this.$nextTick(() => {
+        const textarea = this.$refs.logInput?.$el.querySelector('textarea')
+        if (textarea) textarea.scrollTop = textarea.scrollHeight
+      })
+    },
+  },
+  methods: {
+    record(name, value) {
+      this.events.push({ id: ++this.eventId, name, value })
+      if (this.events.length > 12) this.events.shift()
+    },
+  },
+}
+</script>
+
+<template>
+  <div class="example">
+    <section class="input-section" aria-label="输入框">
+      <form @submit.prevent="record('submit', value)">
+        <AppleInput
+          ref="input"
+          v-model="value"
+          label="姓名"
+          placeholder="怎么称呼你"
+          hint="用于在应用中显示你的名称。"
+          clearable
+          @update:model-value="record('update:modelValue', $event)"
+          @change="record('change', $event)"
+          @clear="record('clear')"
+          @focus="record('focus')"
+          @blur="record('blur')"
+        >
+          <!-- prefix -->
+          <!-- suffix -->
+        </AppleInput>
+        <div class="actions">
+          <AppleLink as="button" :disabled="false" @click="$refs.input.focus()">focus()</AppleLink>
+          <AppleLink as="button" @click="value = 0">赋值为 0</AppleLink>
+          <AppleLink as="button" type="submit">表单校验</AppleLink>
+        </div>
+      </form>
+      <output>v-model = {{ JSON.stringify(value) }} · {{ typeof value }}</output>
+    </section>
+    <section class="events-section" aria-label="事件记录">
+      <div class="event-heading"><h3>事件记录</h3><AppleLink as="button" @click="events = []">清除记录</AppleLink></div>
+      <AppleTextarea ref="logInput" :model-value="eventLog" readonly :rows="6" :resize="false" class="event-log" aria-label="事件记录内容" placeholder="等待操作…" />
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.example { display: grid; gap: 28px; max-width: 560px; margin-inline: auto; padding: 28px 24px; }
+.input-section { display: grid; gap: 16px; min-width: 0; }
+form { display: grid; gap: 16px; min-width: 0; }
+.actions { display: flex; flex-wrap: wrap; align-items: center; gap: 24px; }
+output { color: var(--apple-secondary); font-size: 12px; line-height: 1.6; font-family: ui-monospace, SFMono-Regular, monospace; overflow-wrap: anywhere; }
+.events-section { display: grid; gap: 12px; min-width: 0; border-top: 1px solid var(--apple-border); padding-top: 20px; }
+.event-heading { display: flex; align-items: center; justify-content: space-between; gap: 12px; }
+.event-heading h3 { margin: 0; font-size: 14px; font-weight: 600; }
+.example :deep(.event-log) { height: 240px; max-height: 240px; font-size: 12px; font-family: ui-monospace, SFMono-Regular, monospace; }
+@media (max-width: 480px) { .example { padding: 24px 16px; } }
+</style>

package/templates/playground/src/editor/AppleInputPreview.vue

@@ -0,0 +1,82 @@
+<template>
+  <div class="input-playground" data-testid="input-playground">
+    <LiveVueEditor :files="files" :baseline-files="baselineFiles" reset-label="恢复当前配置" active-file="App.vue" preview-surface @restore="reset">
+      <template #configuration>
+    <section class="configuration" role="region" aria-label="输入框配置">
+      <div class="config-heading"><h3>配置输入框</h3><AppleLink as="button" @click="reset">重置</AppleLink></div>
+        <div class="preset-segments"><AppleSegmentedControl :model-value="preset" label="快速场景" :items="presets" @update:model-value="applyPreset(String($event))" /></div>
+        <div class="preset-select"><AppleSelect :model-value="preset" label="快速场景" :items="presets" @update:model-value="applyPreset(String($event))" /></div>
+        <AppleSegmentedControl v-model="config.type" label="输入类型" :items="types" />
+        <div class="config-grid">
+          <AppleInput v-model="config.label" label="标签" hint="label" />
+          <AppleInput v-model="config.placeholder" label="占位文字" hint="placeholder" />
+          <AppleInput v-model="config.hint" label="帮助文字" hint="hint" />
+          <AppleInput v-model="config.error" label="错误信息" hint="error" placeholder="留空恢复正常" />
+        </div>
+        <div class="switch-grid">
+          <AppleSwitch v-for="toggle in toggles" :key="toggle.key" v-model="config[toggle.key]" :label="toggle.label" :hint="toggle.key" />
+        </div>
+        <AppleAccordion class="advanced-config" :items="[{ label: '插槽、原生属性与动效', value: 'advanced' }]">
+          <template #item>
+          <div class="config-grid">
+            <AppleSegmentedControl v-model="config.prefixMode" label="前缀插槽" hint="prefix" :items="affixModes" />
+            <AppleInput v-if="config.prefixMode === 'text'" v-model="config.prefix" label="前缀文字" placeholder="例如 ¥" />
+            <AppleInput v-if="config.prefixMode === 'icon'" v-model="config.prefixIcon" label="前缀图标代号" placeholder="Mail" hint="Lucide 代号，例如 Mail、User、Search。" :error="iconCodeError(config.prefixIcon)" />
+            <AppleSegmentedControl v-model="config.suffixMode" label="后缀插槽" hint="suffix" :items="affixModes" />
+            <AppleInput v-if="config.suffixMode === 'text'" v-model="config.suffix" label="后缀文字" placeholder="例如 kg" />
+            <AppleInput v-if="config.suffixMode === 'icon'" v-model="config.suffixIcon" label="后缀图标代号" placeholder="Search" hint="Lucide 代号，例如 Search、Check、ArrowRight。" :error="iconCodeError(config.suffixIcon)" />
+            <AppleSelect v-model="config.motion" label="动效" hint="motion" :items="motions" />
+            <AppleInput v-model="config.name" label="表单字段" hint="name" />
+            <AppleInput v-model="config.ariaLabel" label="可访问名称" hint="aria-label" />
+            <AppleInput v-model="config.maxlength" label="最大长度" hint="maxlength" type="number" min="0" placeholder="不限制" />
+            <AppleSelect v-model="config.autocomplete" label="自动填充" hint="autocomplete" :items="autocompletes" />
+            <AppleInput v-model="config.min" label="最小值" hint="min" type="number" :disabled="config.type !== 'number'" />
+            <AppleInput v-model="config.max" label="最大值" hint="max" type="number" :disabled="config.type !== 'number'" />
+            <AppleInput v-model="config.step" label="步长" hint="step" type="number" min="0" :disabled="config.type !== 'number'" />
+          </div>
+          </template>
+        </AppleAccordion>
+    </section>
+      </template>
+    </LiveVueEditor>
+  </div>
+</template>
+<script setup lang="ts">
+import { computed, defineAsyncComponent, reactive, ref } from 'vue'
+import { AppleInput, AppleButton, AppleLink, AppleSelect, AppleSegmentedControl, AppleSwitch, AppleAccordion } from 'apptify'
+import { createInputConfig, generateInputCode, iconCodeError } from './input-playground'
+const LiveVueEditor = defineAsyncComponent(() => import('./LiveVueEditor.vue'))
+const baselineFiles = { 'App.vue': generateInputCode(createInputConfig(), 'Apptify') }
+const config = reactive(createInputConfig())
+const value = ref<string | number>('Apptify')
+const preset = ref('basic')
+const options = (values: string[]) => values.map(value => ({ label: value, value }))
+const presets = [{ label: '基础', value: 'basic' }, { label: '密码', value: 'password' }, { label: '邮箱', value: 'email' }, { label: '金额', value: 'amount' }]
+const types = [{ label: '文本', value: 'text' }, { label: '密码', value: 'password' }, { label: '数字', value: 'number' }, { label: '邮箱', value: 'email' }, { label: '搜索', value: 'search' }, { label: '电话', value: 'tel' }, { label: '网址', value: 'url' }]
+const affixModes = [{ label: '无', value: 'none' }, { label: '文字', value: 'text' }, { label: '图标', value: 'icon' }]
+const motions = options(['inherit', 'auto', 'full', 'reduced', 'none'])
+const autocompletes = options(['off', 'on', 'name', 'email', 'username', 'current-password', 'new-password', 'tel', 'url'])
+const toggles = [{ key: 'clearable', label: '允许清空' }, { key: 'disabled', label: '禁用' }, { key: 'loading', label: '加载' }, { key: 'required', label: '必填' }] as const
+function applyPreset(next: string) {
+  Object.assign(config, createInputConfig())
+  preset.value = next
+  value.value = 'Apptify'
+  if (next === 'password') { Object.assign(config, { type: 'password', label: '密码', placeholder: '请输入密码', hint: '点击眼睛切换密码可见性。', autocomplete: 'current-password' }); value.value = 'apple123' }
+  if (next === 'email') { Object.assign(config, { type: 'email', label: '电子邮箱', placeholder: 'name@example.com', hint: '提交时体验原生邮箱校验。', required: true, autocomplete: 'email', prefixMode: 'icon', prefixIcon: 'Mail' }); value.value = '' }
+  if (next === 'amount') { Object.assign(config, { type: 'number', label: '金额', placeholder: '0.00', hint: '数字输入事件仍返回字符串。', prefixMode: 'text', prefix: '¥', suffixMode: 'text', suffix: '元', min: '0', step: '0.01' }); value.value = 128 }
+}
+function reset() { applyPreset('basic') }
+const files = computed(() => ({ 'App.vue': generateInputCode(config, value.value) }))
+</script>
+<style scoped>
+.input-playground { display: grid; gap: 24px; min-width: 0; }
+.preset-select { display: none; }
+.configuration { display: grid; gap: 20px; }
+.config-heading { display: flex; align-items: center; justify-content: space-between; }
+.config-heading h3 { margin: 0; font-size: 16px; }
+.config-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px; }
+.switch-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px; }
+.advanced-config :deep(.apple-accordion__item > h3) { font-size: 14px; }
+.advanced-config :deep(.apple-accordion__content) { padding: 8px 12px 20px; }
+@media (max-width: 1100px) { .preset-segments { display: none; } .preset-select { display: block; } .config-grid, .switch-grid { grid-template-columns: minmax(0, 1fr); } }
+</style>

package/templates/playground/src/editor/ComponentDocumentLink.vue

@@ -0,0 +1,19 @@
+<template>
+  <footer class="documentation-entry">
+    <router-link :to="href" custom v-slot="{ href: target, navigate }">
+      <apple-link :href="target" @click="navigate"><span>{{ label || '代码与 API' }}</span><ArrowUpRight :size="16" :stroke-width="1.5" aria-hidden="true" /></apple-link>
+    </router-link>
+  </footer>
+</template>
+<script setup lang="ts">
+import { ArrowUpRight } from 'lucide-vue-next'
+defineProps<{ href: string; label?: string }>()
+</script>
+<style scoped>
+.documentation-entry { border-top: 1px solid color-mix(in srgb, var(--apple-border) 45%, transparent); border-radius: 0 0 18px 18px; overflow: hidden; }
+.documentation-entry :deep(.apple-link) { display: flex; align-items: center; justify-content: space-between; width: 100%; min-height: 44px; gap: 8px; padding: 13px 28px; color: var(--apple-secondary); font-size: 11px; font-weight: 400; line-height: 1.25; transition: color var(--apple-fast), background-color var(--apple-fast); }
+.documentation-entry :deep(.apple-link__content) { width: 100%; justify-content: space-between; }
+.documentation-entry :deep(.apple-link:hover) { color: var(--apple-secondary); background: var(--apple-hover); }
+.documentation-entry :deep(.apple-link:active) { background: var(--apple-pressed); }
+@media (max-width: 800px) { .documentation-entry :deep(.apple-link) { padding-inline: 18px; } }
+</style>

package/templates/playground/src/editor/ComponentWorkshop.vue

@@ -0,0 +1,81 @@
+<template>
+  <div class="workshop" data-testid="component-document">
+    <section v-for="section in apiSections" :key="section.id" :id="section.id" class="api-section">
+      <header class="section-heading"><h2>{{ section.title }}</h2><span>{{ section.entries.length }} 项接口</span></header>
+      <div class="api-group">
+        <article v-for="entry in section.entries" :key="entry.id" :id="entry.id" class="api-entry" :data-api="entry.id">
+          <div class="api-summary">
+            <div class="api-signature">
+              <h3><code>{{ entry.name }}</code></h3>
+              <code class="api-type">{{ entry.type }}</code>
+              <div v-if="entry.default !== undefined" class="api-default"><span>默认值</span><code>{{ entry.default }}</code></div>
+            </div>
+            <p class="api-description">{{ entry.description }}</p>
+          </div>
+          <apple-accordion v-if="entry.example" class="api-accordion" :model-value="activeApi === entry.id ? entry.id : []" :items="[{ label: '交互示例', value: entry.id }]" @update:model-value="value => toggleExample(entry.id, value)">
+            <template #item="{ open }">
+              <div v-if="open && activeApi === entry.id" class="api-example">
+                <div class="example-introduction"><h4>{{ entry.example.title }}</h4><p>{{ entry.example.description }}</p></div>
+                <LiveVueEditor :key="entry.id" :files="apiFiles(entry)" :baseline-files="{ 'App.vue': entry.example.code }" active-file="App.vue" @save="files => saveApi(entry.id, files)" />
+              </div>
+            </template>
+          </apple-accordion>
+        </article>
+      </div>
+    </section>
+    <section id="accessibility" class="api-section">
+      <header class="section-heading"><h2>交互与无障碍</h2></header>
+      <ul class="api-notes"><li v-for="note in doc.notes" :key="note">{{ note }}</li></ul>
+    </section>
+  </div>
+</template>
+<script setup lang="ts">
+import { computed, defineAsyncComponent, ref } from 'vue'
+import type { ApiEntry, ComponentDocument } from './contract'
+import { documentSections } from './sections'
+const props = defineProps<{ doc: ComponentDocument }>()
+// Additional editors are mounted only for examples not covered by the main demo.
+const LiveVueEditor = defineAsyncComponent(() => import('./LiveVueEditor.vue'))
+const activeApi = ref<string>()
+const apiDrafts = new Map<string, Record<string, string>>()
+const apiSections = computed(() => documentSections(props.doc))
+function toggleExample(id: string, value: unknown) { activeApi.value = value === id ? id : undefined }
+function apiFiles(entry: ApiEntry) { return apiDrafts.get(entry.id) || { 'App.vue': entry.example!.code } }
+function saveApi(id: string, files: Record<string, string>) { apiDrafts.set(id, files) }
+</script>
+<style scoped>
+.workshop { min-width: 0; }
+.api-section { scroll-margin-top: 100px; margin-top: 40px; }
+.section-heading { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; margin-bottom: 16px; }
+.section-heading h2 { margin: 0; font-size: 22px; letter-spacing: -.02em; }
+.section-heading > span { color: var(--apple-secondary); font-size: 12px; }
+.api-group { border-top: 1px solid var(--apple-border); }
+.api-entry { scroll-margin-top: 100px; }
+.api-entry + .api-entry { border-top: 1px solid var(--apple-border); }
+.api-summary { display: grid; grid-template-columns: minmax(0, 220px) minmax(0, 1fr); gap: 28px; padding: 24px 0; }
+.api-signature { min-width: 0; }
+.api-signature h3 { margin: 0 0 8px; font-size: 15px; line-height: 1.5; overflow-wrap: anywhere; }
+.api-signature code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.api-type { display: block; color: var(--apple-secondary); font-size: 12px; line-height: 1.65; overflow-wrap: anywhere; }
+.api-default { display: flex; align-items: baseline; flex-wrap: wrap; gap: 8px; margin-top: 12px; font-size: 12px; }
+.api-default > span { color: var(--apple-secondary); }
+.api-default > code { padding: 2px 6px; border-radius: 4px; background: var(--apple-surface-alt); overflow-wrap: anywhere; }
+.api-description { margin: 0; font-size: 14px; line-height: 1.85; overflow-wrap: anywhere; }
+.api-accordion { margin: 0; }
+.api-accordion :deep(.apple-accordion__item) { border-bottom: 0; }
+.api-accordion :deep(.apple-accordion__item > h3) { margin: 0; }
+.api-accordion :deep(.apple-accordion__item > h3 > button) { padding: 16px 24px; font-size: 13px; }
+.api-accordion :deep(.apple-accordion__content) { padding: 0 24px 24px; }
+.example-introduction { padding: 16px 0 8px; }
+.example-introduction h4 { margin: 0 0 6px; font-size: 16px; }
+.example-introduction p { margin: 0; color: var(--apple-secondary); font-size: 13px; line-height: 1.7; }
+.api-notes { padding-left: 18px; margin: 0; font-size: 14px; line-height: 1.85; }
+.api-notes li + li { margin-top: 14px; }
+@media (max-width: 1100px) { .api-summary { grid-template-columns: minmax(0, 180px) minmax(0, 1fr); gap: 20px; } }
+@media (max-width: 720px) {
+  .api-summary { grid-template-columns: minmax(0, 1fr); padding: 20px 0; gap: 14px; }
+  .api-default { margin-top: 8px; }
+  .section-heading h2 { font-size: 20px; }
+  .api-accordion :deep(.apple-accordion__content) { padding: 0 20px 20px; }
+}
+</style>

package/templates/playground/src/editor/ConfigurableEditor.vue

@@ -0,0 +1,35 @@
+<template>
+  <div class="configurable-editor">
+    <div class="mode-selector"><AppleTabs v-model="mode" :items="[{ label: '低代码', value: 'controls' }, { label: 'App.vue', value: 'code' }]" label="编辑模式" /><slot name="actions" /></div>
+    <div v-show="mode === 'controls'" class="controls-pane"><slot /></div>
+    <div v-show="mode === 'code'" class="source-pane"><CodeMirror ref="editor" v-bind="editorAttrs" :value="String(editorAttrs.value ?? '')" :filename="String(editorAttrs.filename ?? 'App.vue')" /></div>
+  </div>
+</template>
+<script setup lang="ts">
+import { ref, watch, nextTick } from 'vue'
+import CodeMirror from '@vue/repl/codemirror-editor'
+import { AppleTabs } from 'apptify'
+defineProps<{ editorAttrs: Record<string, unknown> }>()
+const mode = ref('controls')
+const editor = ref<InstanceType<typeof CodeMirror>>()
+watch(mode, async mode => {
+  await nextTick()
+  if (mode === 'code') editor.value?.getEditorIns<'codemirror'>()?.refresh()
+})
+defineExpose({ getEditorIns: () => editor.value?.getEditorIns() })
+</script>
+<style scoped>
+.configurable-editor { height: 100%; display: flex; flex-direction: column; min-height: 0; background: var(--apple-surface); }
+.mode-selector { box-sizing: border-box; flex: 0 0 var(--header-height, 49px); display: flex; align-items: center; justify-content: space-between; gap: 8px; padding: 0 12px; border-bottom: 1px solid var(--apple-border); }
+.mode-selector :deep(.apple-tabs__list) { border-bottom: 0; }
+.mode-selector :deep(.apple-tabs__viewport) { display: none; }
+.controls-pane { flex: 1; min-height: 0; overflow: auto; padding: 20px; }
+/* Vue REPL resets every descendant button, including the library select trigger. */
+.controls-pane :deep(.apple-select) { border: 1px solid var(--apple-border); background: var(--apple-surface); }
+.controls-pane :deep(.apple-select:hover:where(:not([data-apple-touch] *)):not(:disabled)) { border-color: color-mix(in srgb, var(--apple-secondary) 60%, var(--apple-border)); }
+.controls-pane :deep(.apple-select:active:not(:disabled)) { background: color-mix(in srgb, var(--apple-text) 7%, var(--apple-surface)); }
+.controls-pane :deep(.apple-select:focus) { border-color: var(--apple-accent); }
+.controls-pane :deep(.apple-field.has-error .apple-select) { border-color: var(--apple-danger); }
+.controls-pane :deep(.apple-select:disabled) { border-color: var(--apple-surface-alt); background: var(--apple-surface-alt); cursor: not-allowed; }
+.source-pane { flex: 1; min-height: 0; position: relative; }
+</style>

package/templates/playground/src/editor/LiveVueEditor.vue

@@ -0,0 +1,133 @@
+<template>
+  <div ref="editorRoot" class="live-editor" :class="{ dark: theme === 'dark', 'has-configuration': !!slots.configuration }">
+    <EditorActions v-if="!slots.configuration" />
+    <Repl ref="repl" :store="store" :editor="slots.configuration ? configuredEditor : CodeMirror" layout="horizontal" layout-reverse preview-theme :theme="theme" :show-import-map="false" :show-ts-config="false" :show-compile-output="false" :show-ssr-output="false" :auto-resize="false" :clear-console="false" :preview-options="previewOptions" :editor-options="{ showErrorText: slots.configuration ? false : '显示错误', autoSaveText: false }" />
+    <p class="editor-status" role="status">{{ copied ? '已复制当前文件' : '实时预览 · Vue 源码 · 自动编译' }}</p>
+  </div>
+</template>
+<script setup lang="ts">
+import { computed, defineComponent, h, onBeforeUnmount, onMounted, ref, useSlots, watch, nextTick } from 'vue'
+import { File, Repl, useStore } from '@vue/repl'
+import CodeMirror from '@vue/repl/codemirror-editor'
+import ConfigurableEditor from './ConfigurableEditor.vue'
+import { AppleLink, AppleTooltip, useApple } from 'apptify'
+import { Copy, RefreshCw, RotateCcw } from 'lucide-vue-next'
+const props = defineProps<{ files: Record<string, string>; activeFile?: string; resetLabel?: string; baselineFiles?: Record<string, string>; previewSurface?: boolean }>()
+const emit = defineEmits<{ close: []; save: [files: Record<string, string>]; restore: [] }>()
+const slots = useSlots()
+const configuredEditor = defineComponent({
+  inheritAttrs: false,
+  setup(_, { attrs, expose }) {
+    const pane = ref<InstanceType<typeof ConfigurableEditor>>()
+    expose({ getEditorIns: () => pane.value?.getEditorIns() })
+    return () => h(ConfigurableEditor, { ref: pane, editorAttrs: attrs }, { default: slots.configuration, actions: () => h(EditorActions) })
+  },
+})
+const EditorActions = () => h('div', { class: 'editor-actions', role: 'group', 'aria-label': '示例操作' }, [
+  { label: '重新运行', icon: RefreshCw, click: rerun },
+  { label: props.resetLabel || '恢复示例', icon: RotateCcw, click: restore },
+  { label: '复制当前文件', icon: Copy, click: copyCode },
+].map(action => {
+  const button = () => h(AppleLink, {
+  as: 'button', iconOnly: !!slots.configuration,
+  icon: slots.configuration ? action.icon : undefined,
+  label: action.label, onClick: action.click,
+  }, { default: () => slots.configuration ? null : action.label })
+  return slots.configuration ? h(AppleTooltip, { text: action.label }, { default: button }) : button()
+}))
+const apple = useApple()
+const theme = computed(() => apple.theme.value.current.scheme === 'dark' ? 'dark' : 'light')
+const repl = ref<InstanceType<typeof Repl>>()
+const editorRoot = ref<HTMLElement>()
+const copied = ref(false)
+let copyTimer: ReturnType<typeof setTimeout> | undefined
+const url = (name: string) => new URL(`${import.meta.env.BASE_URL}assets/editor/${name}`, location.origin).href
+const importMap = { imports: { vue: url('vue.js'), apptify: url('runtime.js'), 'lucide-vue-next': url('runtime.js') } }
+const normalize = (name: string) => name.startsWith('src/') ? name : `src/${name}`
+const initialFiles: Record<string, File> = Object.fromEntries(Object.entries(props.files)
+  .filter(([name]) => name.endsWith('.vue'))
+  .map(([name, code]) => [normalize(name), new File(normalize(name), code)]))
+// REPL reads the map synchronously during useStore/init and after setFiles.
+// Seed it before either call, rather than allowing a missing-map error to linger.
+initialFiles['import-map.json'] = new File('import-map.json', JSON.stringify(importMap), true)
+const store = useStore({
+  files: ref(initialFiles), mainFile: ref('src/App.vue'),
+  template: ref({ welcomeSFC: props.files['App.vue'] || props.files['src/App.vue'], newSFC: '<template></template>' }),
+  activeFilename: ref('src/App.vue'),
+  builtinImportMap: ref(importMap), vueVersion: ref(null),
+  resourceLinks: ref({ esModuleShims: url('shims.js') }),
+})
+let disposed = false
+let applying = Promise.resolve(true)
+const previewOptions = computed(() => ({
+  headHTML: `<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'unsafe-inline' blob: ${location.origin}; style-src 'unsafe-inline' blob: ${location.origin}; connect-src blob: ${location.origin}; img-src data: blob:; font-src data:; form-action 'none'; base-uri 'none'"><link rel="stylesheet" href="${url('runtime.css')}"><script>window.addEventListener('keydown', event => { if (event.key === 'Escape') { event.preventDefault(); parent.postMessage({ action: 'apptify-workshop-close' }, '*') } })<\/script><style>body{margin:0;background:var(${props.previewSurface ? '--apple-surface' : '--apple-bg'});color:var(--apple-text);min-height:100vh}html{min-height:100%}</style>`,
+  customCode: { importCode: "import { watchEffect } from 'vue'; import { createAppleUI, themeStyle, resolveMotion } from 'apptify'", useCode: `const ui = createAppleUI(${JSON.stringify({ theme: 'preview', themes: { preview: apple.theme.value.current }, persist: false, motion: apple.motion.value.mode })}); app.use(ui); ui.attach(); document.documentElement.classList.add('apple-provider'); const stopPreviewPreferences = watchEffect(() => { for (const [key, value] of Object.entries(themeStyle(ui))) document.documentElement.style.setProperty(key, value); document.documentElement.style.colorScheme = ui.theme.value.current.scheme; document.documentElement.dataset.appleMotion = resolveMotion('inherit', ui.motion.value.mode, ui.motion.value.reduced); }); app.onUnmount(() => { stopPreviewPreferences(); ui.detach(); });` },
+  showRuntimeError: true, showRuntimeWarning: true,
+}))
+function apply(files: Record<string, string>) {
+  // Serialize restores so rapid clicks cannot install an older compilation last.
+  applying = applying.then(async () => {
+    if (disposed) return false
+    const editable = Object.keys(store.files).filter(name => name.endsWith('.vue'))
+    const incoming = Object.keys(files).filter(name => name.endsWith('.vue'))
+    if (editable.length === incoming.length && incoming.every(name => store.files[normalize(name)])) {
+      // Editing the existing File lets REPL compile once without rebuilding its iframe.
+      for (const name of incoming) store.files[normalize(name)].code = files[name]
+    } else {
+      await store.setFiles({ ...files, 'import-map.json': JSON.stringify(importMap) }, 'App.vue')
+    }
+    if (!disposed && props.activeFile && store.files[normalize(props.activeFile)]) store.setActive(normalize(props.activeFile))
+    return !disposed
+  }).catch(error => { if (!disposed) store.errors = [error instanceof Error ? error : String(error)]; return false })
+  return applying
+}
+function rerun() {
+  if (!repl.value) return
+  try { repl.value.reload(); apple.notify('正在重新运行示例', { tone: 'info' }) }
+  catch { apple.notify('重新运行失败，请查看编辑器中的错误', { tone: 'danger' }) }
+}
+async function restore() {
+  emit('restore')
+  await nextTick()
+  const restored = await apply(props.baselineFiles || props.files)
+  if (!disposed) apple.notify(restored ? (slots.configuration ? '已恢复默认配置和代码' : '已恢复示例代码') : '恢复失败，请查看编辑器中的错误', { tone: restored ? 'success' : 'danger' })
+}
+watch(() => props.files, () => apply(props.files))
+async function copyCode() {
+  try { await navigator.clipboard.writeText(store.activeFile.code); apple.notify('已复制当前文件代码', { tone: 'success' }); copied.value = true; clearTimeout(copyTimer); copyTimer = setTimeout(() => copied.value = false, 2000) }
+  catch { apple.notify('无法访问剪贴板，请在编辑器中选择代码复制', { tone: 'warning' }) }
+}
+function previewMessage(event: MessageEvent) {
+  const frame = editorRoot.value?.querySelector<HTMLIFrameElement>('.vue-repl iframe')
+  if (frame && event.source === frame.contentWindow && event.data?.action === 'apptify-workshop-close') emit('close')
+}
+onMounted(() => {
+  // init() compiles the active file and skips mainFile in its remaining loop.
+  // Start on App.vue so the preview entry is compiled, then reveal the source.
+  if (props.activeFile) store.setActive(normalize(props.activeFile))
+  window.addEventListener('message', previewMessage)
+})
+onBeforeUnmount(() => { disposed = true; clearTimeout(copyTimer); window.removeEventListener('message', previewMessage); emit('save', store.getFiles()) })
+</script>
+<style scoped>
+.has-configuration :deep(.vue-repl) { --header-height: 49px; height: 780px; }
+.has-configuration :deep(.tab-buttons button) { height: 100%; display: inline-flex; align-items: center; }
+.has-configuration :deep(.split-pane > .right .file-selector) { display: none; }
+.has-configuration :deep(.split-pane > .right .editor-container) { height: 100%; }
+.editor-actions { display: flex; flex-wrap: wrap; gap: 8px; margin: 12px 0; }
+.has-configuration .editor-actions { flex-wrap: nowrap; gap: 2px; margin: 0; }
+.editor-status { margin: 8px 0; color: var(--apple-secondary); font-size: 12px; }
+:deep(.vue-repl) { height: 580px; border: 1px solid var(--apple-separator); border-radius: 12px; overflow: hidden; }
+
+@media (max-width: 720px) {
+  :deep(.vue-repl) { height: 740px; }
+  .has-configuration :deep(.vue-repl) { height: 1200px; }
+  .live-editor:not(.has-configuration) .editor-actions { display: grid; grid-template-columns: repeat(3, 1fr); gap: 4px; }
+  .editor-actions :deep(button) { padding-inline: 8px; font-size: 12px; min-height: 36px; }
+  :deep(.split-pane) { display: flex !important; flex-direction: column !important; }
+  :deep(.split-pane > .left), :deep(.split-pane > .right) { position: relative !important; inset: auto !important; z-index: 0 !important; pointer-events: auto !important; display: block !important; height: 50% !important; width: 100% !important; }
+  :deep(.split-pane > .left) { height: 55% !important; }
+  :deep(.split-pane > .right) { height: 45% !important; }
+  :deep(.split-pane .toggler) { display: none !important; }
+}
+</style>

package/templates/playground/src/editor/apple-input-source.ts

@@ -0,0 +1,2 @@
+// Generated by tooling/prepare-input-source.mjs; do not edit the snapshot by hand.
+export default "<!-- AppleInput 同源实现：src/components/forms.ts + src/styles/forms.css。\n只移除 TypeScript 类型并转接浏览器公开依赖，保留 Options API/render 实现。 -->\n<script>\nimport { defineComponent, h, useId } from 'vue';\nimport { ripple } from 'apptify';\nimport { Eye, EyeOff, LoaderCircle, X } from 'lucide-vue-next';\nconst fieldProps = {\n    label: { type: String, default: '' },\n    hint: { type: String, default: '' },\n    error: { type: String, default: '' },\n    disabled: Boolean,\n    loading: Boolean,\n    required: Boolean,\n    motion: { type: String, default: 'inherit' },\n};\nfunction fieldId(vm) { return String(vm.$attrs.id || vm.inputId); }\nfunction controlAttrs(vm, hasLabel = !!vm.label) {\n    return {\n        ...vm.$attrs,\n        id: fieldId(vm),\n        disabled: vm.disabled || vm.loading,\n        required: vm.required,\n        'aria-label': vm.$attrs['aria-label'] || vm.label || undefined,\n        'aria-labelledby': vm.$attrs['aria-labelledby'] || (!vm.$attrs['aria-label'] && hasLabel ? `${fieldId(vm)}-label` : undefined),\n        'aria-invalid': vm.error ? true : undefined,\n        'aria-busy': vm.loading || undefined,\n        'aria-describedby': [vm.$attrs['aria-describedby'], (vm.error || vm.hint) ? `${fieldId(vm)}-message` : ''].filter(Boolean).join(' ') || undefined,\n    };\n}\nfunction field(vm, control, classes = '', error = vm.error) {\n    return h('div', {\n        class: ['apple-field', classes, { 'is-disabled': vm.disabled, 'has-error': !!error }],\n        'data-apple-motion': vm.motion,\n    }, [\n        vm.label ? h('span', { class: 'apple-field__label', id: `${fieldId(vm)}-label` }, [vm.label, vm.required ? h('span', { 'aria-hidden': true, class: 'apple-field__required' }, ' *') : null]) : null,\n        control,\n        error || vm.hint ? h('p', { id: `${fieldId(vm)}-message`, class: ['apple-field__message', { 'is-error': !!error }], role: error ? 'alert' : undefined }, error || vm.hint) : null,\n    ]);\n}\nfunction spinner() { return h(LoaderCircle, { size: 18, class: 'apple-control__spinner', 'aria-hidden': true }); }\nfunction stringValue(event) { return event.target.value; }\nexport const AppleInput = defineComponent({\n    name: 'AppleInput', inheritAttrs: false,\n    props: { ...fieldProps, modelValue: { type: [String, Number], default: '' }, type: { type: String, default: 'text' }, placeholder: String, clearable: Boolean },\n    emits: ['update:modelValue', 'change', 'clear'],\n    data() { return { inputId: useId(), passwordVisible: false }; },\n    methods: { focus() { this.$refs.input?.focus(); } },\n    render() {\n        const inactive = this.disabled || this.loading;\n        return field(this, h('div', { class: 'apple-input-wrap' }, [\n            this.$slots.prefix ? h('span', { class: 'apple-input__affix' }, this.$slots.prefix()) : null,\n            h('input', { ...controlAttrs(this), ref: 'input', class: ['apple-control', this.$attrs.class], type: this.type === 'password' && this.passwordVisible ? 'text' : this.type, placeholder: this.placeholder, value: this.modelValue,\n                onInput: (event) => this.$emit('update:modelValue', stringValue(event)), onChange: (event) => this.$emit('change', stringValue(event)),\n            }),\n            this.loading ? spinner() : null,\n            !inactive && this.clearable && String(this.modelValue).length ? ripple(h('button', { type: 'button', class: 'apple-field__icon', 'aria-label': '清空', title: '清空', onClick: () => { this.$emit('update:modelValue', ''); this.$emit('clear'); this.focus(); } }, h(X, { size: 16 }))) : null,\n            !inactive && this.type === 'password' ? ripple(h('button', { type: 'button', class: 'apple-field__icon', 'aria-label': this.passwordVisible ? '隐藏密码' : '显示密码', title: this.passwordVisible ? '隐藏密码' : '显示密码', 'aria-pressed': this.passwordVisible, onClick: () => { this.passwordVisible = !this.passwordVisible; } }, h(this.passwordVisible ? EyeOff : Eye, { size: 18 }))) : null,\n            this.$slots.suffix ? h('span', { class: 'apple-input__affix' }, this.$slots.suffix()) : null,\n        ]));\n    },\n});\nexport default AppleInput;\n</script>\n\n<style>\n.apple-field { display: flex; flex-direction: column; gap: 8px; min-width: 0; color: var(--apple-text); font: inherit; }\n.apple-field__label { font-size: 14px; font-weight: 600; line-height: 1.4; overflow-wrap: anywhere; }\n.apple-field__required, .apple-field__message.is-error { color: var(--apple-danger); }\n.apple-field__message { margin: 0; color: var(--apple-secondary); font-size: 12px; line-height: 1.5; overflow-wrap: anywhere; }\n.apple-field__counter { align-self: flex-end; color: var(--apple-secondary); font-size: 12px; font-variant-numeric: tabular-nums; }\n.apple-control { box-sizing: border-box; min-width: 0; width: 100%; min-height: 48px; border: 1px solid var(--apple-border); border-radius: 8px; padding: 11px 14px; background: var(--apple-surface); color: var(--apple-text); font: inherit; font-size: 16px; line-height: 1.5; transition: border-color var(--apple-duration-fast, 120ms) ease, box-shadow var(--apple-duration-fast, 120ms) ease, background-color var(--apple-duration-fast, 120ms) ease, color var(--apple-duration-fast, 120ms) ease; }\n.apple-field .apple-control { font-size: 16px; }\n.apple-control::placeholder { color: var(--apple-secondary); opacity: 1; }\n.apple-control:hover:where(:not([data-apple-touch] *)):not(:disabled) { border-color: color-mix(in srgb, var(--apple-secondary) 60%, var(--apple-border)); }\n.apple-control:focus { border-color: var(--apple-accent); outline: none; box-shadow: 0 0 0 3px color-mix(in srgb, var(--apple-accent) 20%, transparent); }\n.apple-field.has-error .apple-control, .apple-field.has-error .apple-input-wrap { border-color: var(--apple-danger); }\n.apple-control:disabled, .apple-choice:has(input:disabled), .apple-switch-row:has(input:disabled), .apple-field .is-disabled { opacity: .5; cursor: not-allowed; }\n.apple-field .apple-control:disabled { background: var(--apple-surface-alt); border-color: var(--apple-surface-alt); }\n.apple-input-wrap { display: flex; align-items: center; min-width: 0; border: 1px solid var(--apple-border); border-radius: 8px; background: var(--apple-surface); transition: border-color var(--apple-duration-fast, 120ms) ease, box-shadow var(--apple-duration-fast, 120ms) ease, background-color var(--apple-duration-fast, 120ms) ease; }\n.apple-input-wrap:hover:where(:not([data-apple-touch] *)):not(:has(input:disabled)) { border-color: color-mix(in srgb, var(--apple-secondary) 60%, var(--apple-border)); }\n.apple-input-wrap:focus-within { border-color: var(--apple-accent); outline: none; box-shadow: 0 0 0 3px color-mix(in srgb, var(--apple-accent) 20%, transparent); }\n.apple-input-wrap > .apple-control, .apple-input-wrap > .apple-control:focus, .apple-input-wrap > .apple-control:focus-visible { border: 0; background: transparent; box-shadow: none; outline: none; }\n.apple-input-wrap > .apple-control:disabled { background: transparent; }\n.apple-field .apple-input-wrap:has(input:disabled) { background: var(--apple-surface-alt); border-color: var(--apple-surface-alt); }\n.apple-input__affix { display: inline-flex; align-items: center; flex-shrink: 0; max-width: 35%; padding-inline: 12px; color: var(--apple-secondary); overflow-wrap: anywhere; }\n.apple-input-wrap > .apple-input__affix:has(button) { align-self: stretch; align-items: stretch; gap: 0; max-width: none; padding: 0; }\n.apple-input-wrap > .apple-input__affix button { align-self: stretch; box-sizing: border-box; min-height: 44px; padding: 7px 12px; border-width: 1px; border-style: solid; border-radius: 0; line-height: 1.4; }\n.apple-input-wrap > .apple-input__affix button:not(.apple-button) { border-color: transparent; }\n.apple-input-wrap > .apple-input__affix .apple-button--icon, .apple-input-wrap > .apple-input__affix .apple-field__icon { width: 44px; height: auto; padding: 0; }\n.apple-input-wrap > .apple-field__icon { align-self: stretch; height: auto; min-height: 44px; padding: 0; border-radius: 0; }\n.apple-input-wrap > .apple-field__icon:first-child, .apple-input-wrap > .apple-input__affix:first-child > button:first-child { border-radius: 7px 0 0 7px; }\n.apple-input-wrap > .apple-field__icon:last-child, .apple-input-wrap > .apple-input__affix:last-child > button:last-child { border-radius: 0 7px 7px 0; }\n.apple-input__affix + .apple-control { padding-inline-start: 0; }\n.apple-field__icon { position: relative; display: inline-flex; align-items: center; justify-content: center; flex-shrink: 0; width: 44px; height: 44px; border: 0; border-radius: 6px; color: var(--apple-secondary); background: transparent; cursor: pointer; transition: background-color var(--apple-duration-fast, 120ms) ease, color var(--apple-duration-fast, 120ms) ease; }\n.apple-field__icon:hover:where(:not([data-apple-touch] *)):not(:disabled) { color: var(--apple-text); background: var(--apple-surface-alt); }\n.apple-field__icon:active:not(:disabled) { background: color-mix(in srgb, var(--apple-text) 15%, var(--apple-surface)); }\n.apple-field__icon:focus-visible, .apple-stepper__button:focus-visible, .apple-rate__star:focus-visible { outline: 3px solid var(--apple-accent); outline-offset: 2px; }\n.apple-field__icon:disabled, .apple-stepper__button:disabled { opacity: .4; cursor: not-allowed; }\n.apple-control__spinner { flex-shrink: 0; margin-inline: 12px; color: var(--apple-accent); animation: apple-control-spin .9s linear infinite; }\n</style>\n"

package/templates/playground/src/editor/apple-input.ts

@@ -0,0 +1,48 @@
+import type { ComponentDocument, ApiDefinition } from './contract'
+const definitions = {
+  name: 'AppleInput', source: 'src/components/forms.ts:21–89',
+  props: [
+    { name: 'modelValue / v-model', type: 'string | number', default: "''", description: '输入框里显示的内容，用 v-model 绑定。初始值可以是文字或数字；用户输入后，得到的值都是字符串。例如输入 123，得到的是 "123"，不是数字 123。清空后得到空字符串 ""。' },
+    { name: 'type', type: 'string', default: "'text'", description: '设置输入类型，例如 text（普通文字）、password（密码）、number（数字）。密码类型会显示“显示密码”按钮，点击后可以查看或隐藏内容，输入的值不会改变。数字类型仍返回字符串。' },
+    { name: 'placeholder', type: 'string', default: 'undefined', description: '输入框为空时显示的提示文字，开始输入后消失。例如“请输入姓名”。它不能代替字段名称，建议同时设置 label。' },
+    { name: 'clearable', type: 'boolean', default: 'false', description: '设为 true 后，输入框有内容时会显示清空按钮，值为数字 0 时也会显示。点击按钮会清空内容、触发 clear 事件，并让光标回到输入框。禁用或加载时会隐藏清空按钮。' },
+    { name: 'label', type: 'string', default: "''", description: '输入框上方的字段名称，例如“姓名”。字段名称只用于说明，点击输入框本身可进入编辑。屏幕阅读器默认使用它介绍这个字段；可以用 aria-label 单独设置朗读名称。' },
+    { name: 'hint', type: 'string', default: "''", description: '输入框下方的帮助文字，例如“最多输入 20 个字”。如果设置了 error，会优先显示错误信息，暂时隐藏这段帮助。屏幕阅读器也能读到这段说明。' },
+    { name: 'error', type: 'string', default: "''", description: '输入框下方的错误信息，例如“请输入姓名”，同时显示错误样式。把它设为空字符串就能恢复正常。组件只显示你传入的错误，不会自己检查内容，也不会阻止提交。' },
+    { name: 'disabled', type: 'boolean', default: 'false', description: '设为 true 后，输入框不能编辑，清空和密码按钮也会隐藏。按 Tab 会跳过这个字段，提交 HTML 表单时也不会包含这个字段。' },
+    { name: 'loading', type: 'boolean', default: 'false', description: '设为 true 后显示加载图标，表示正在处理。此时不能输入，清空和密码按钮会隐藏，只保留加载图标。处理结束后设为 false，就能继续操作。' },
+    { name: 'required', type: 'boolean', default: 'false', description: '设为 true 后，字段名称旁显示星号。放在 HTML 表单中时，浏览器会检查是否填写；为空就不能正常提交。它不会自动设置 error，也不会生成自定义错误信息。' },
+    { name: 'motion', type: "'inherit' | 'auto' | 'full' | 'reduced' | 'none'", default: "'inherit'", description: '设置这个输入框的动效偏好。默认 inherit，跟随外层设置；none 表示不使用动效，reduced 表示减少动效。这个设置不会改变输入内容或校验结果。' },
+  ],
+  events: [
+    { name: 'update:modelValue', type: '(value: string) => void', description: '输入内容变化时触发，事件参数就是最新的文字；点击清空时，参数是空字符串。使用 v-model 时通常不用手动处理。即使 type 是 number，参数也仍是字符串，需要数字时自行转换。' },
+    { name: 'change', type: '(value: string) => void', description: '修改内容后，把光标移出输入框时通常会触发，事件参数是当前文字。它不会像 update:modelValue 那样每输入一个字就触发。点击组件的清空按钮不会主动触发它。' },
+    { name: 'clear', type: '() => void', description: '点击清空按钮时触发，没有事件参数。触发前，组件已经发出清空内容的更新事件；随后会让光标回到输入框。可以用它处理清空后的操作。' },
+  ],
+  slots: [
+    { name: 'prefix', type: '() => VNode[]（无 slot props）', description: '在输入框内容的左侧放自定义内容，例如 @ 符号或图标。插槽不会提供额外数据。如果放的是按钮，请给按钮设置清楚的名称；纯装饰图标可以用 aria-hidden 隐藏朗读。' },
+    { name: 'suffix', type: '() => VNode[]（无 slot props）', description: '在输入框右侧放自定义内容，例如单位、图标或操作按钮。它位于组件自带的加载、清空、密码按钮之后。插槽不会提供额外数据；直接放在组件里的内容不会显示，需使用具名插槽。' },
+  ],
+  methods: [{ name: 'focus()', type: '() => void', description: '让光标进入输入框。先用 ref 获取组件，再调用 input.value.focus()。例如点击“编辑姓名”后自动聚焦。输入框被禁用时无法聚焦；组件没有提供 blur() 或 select() 方法。' }],
+  notes: [
+    '常见 HTML 输入属性可以直接使用，例如 maxlength 限制长度、autocomplete 自动填充。@focus、@blur、@keydown 也可以直接监听。这些沿用浏览器的行为，不是组件另设的接口。class 和 style 应用在内部输入框上。不要使用 readable。',
+    '不传 id 时，组件会自动生成，保证名称和输入框正确关联。帮助、错误、加载状态也会告知屏幕阅读器；这些状态跟随 hint、error、loading、required 和 disabled。',
+    '可以用 Tab 切换焦点，用键盘选中文字、复制和操作按钮。密码按钮会提示当前是显示还是隐藏；清空后光标回到输入框。如果不显示 label，请设置 aria-label 或 aria-labelledby，让屏幕阅读器知道字段名称。',
+  ],
+}
+
+function entries(group: string, definitions: ApiDefinition[]) {
+  return definitions.map(entry => {
+    const id = entry.name === 'modelValue / v-model' ? 'model-value'
+      : entry.name === 'update:modelValue' ? 'update-model-value'
+      : entry.name === 'focus()' ? 'focus' : entry.name
+    return { ...entry, id: `${group}-${id}` }
+  })
+}
+export default {
+  ...definitions,
+  props: entries('prop', definitions.props),
+  events: entries('event', definitions.events),
+  slots: entries('slot', definitions.slots),
+  methods: entries('method', definitions.methods),
+} satisfies ComponentDocument

package/templates/playground/src/editor/contract.ts

@@ -0,0 +1,14 @@
+/** Public API descriptions are required; component-specific runnable examples are optional. */
+export interface VueExample { title: string; description: string; code: string }
+export interface ApiDefinition { name: string; type: string; default?: string; description: string }
+export interface ApiEntry extends ApiDefinition { id: string; example?: VueExample }
+export interface ComponentDocument {
+  name: string
+  source: string
+  props: ApiEntry[]
+  events: ApiEntry[]
+  slots: ApiEntry[]
+  methods: ApiEntry[]
+  notes: string[]
+  implementation?: { files: Record<string, string>; activeFile: string; description: string }
+}

package/templates/playground/src/editor/documents.ts

@@ -0,0 +1,20 @@
+import { defineAsyncComponent, type Component } from 'vue'
+import type { ComponentDocument } from './contract'
+/** Lightweight route directory. Each document is downloaded only on its own page. */
+export interface DocumentRegistration {
+  name: string
+  label: string
+  description: string
+  group: string
+  preview?: Component
+  load: () => Promise<{ default: ComponentDocument }>
+}
+export const componentDocuments: Record<string, DocumentRegistration> = {
+  'apple-input': {
+    name: 'AppleInput', label: '输入框', group: '表单',
+    description: '从输入、反馈到辅助操作，逐条了解输入框的行为与接口。',
+    preview: defineAsyncComponent(() => import('./AppleInputPreview.vue')),
+    load: () => import('./apple-input'),
+  },
+}
+export const componentDocumentPath = (slug: string) => `/component-docs/${slug}`