apptify 0.6.2 → 0.7.0

package/templates/playground/src/editor/handbooks/apple-transition.ts

@@ -0,0 +1,44 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleTransition",
+  "source": "src/components/motion.ts",
+  "props": [
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "name",
+      "type": "'page' | 'slide-x' | 'slide-y' | 'fade'",
+      "default": "\"slide-y\"",
+      "description": "过渡样式：page、slide-x、slide-y、fade。减少动效时退化为淡入淡出，none 关闭 CSS 过渡。"
+    },
+    {
+      "name": "mode",
+      "type": "'out-in' | 'in-out' | 'default'",
+      "default": "\"out-in\"",
+      "description": "out-in 先离开再进入，in-out 先进入再离开，default 同时进行。"
+    },
+    {
+      "name": "appear",
+      "type": "boolean",
+      "default": "true",
+      "description": "首次渲染时也执行进入过渡。"
+    }
+  ],
+  "events": [],
+  "slots": [
+    {
+      "name": "default",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "单个可过渡元素或组件；切换时提供不同 key。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "default 插槽只放一个可过渡根节点。切换内容使用 key；外部减少动效偏好仍约束过渡。"
+  ]
+})

package/templates/playground/src/editor/handbooks/apple-tree.ts

@@ -0,0 +1,84 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleTree",
+  "source": "src/components/content.ts",
+  "props": [
+    {
+      "name": "searchable",
+      "type": "boolean",
+      "default": "true",
+      "description": "默认显示顶部搜索，匹配名称、value 和描述并保留祖先路径；清空搜索恢复原展开状态。"
+    },
+    {
+      "name": "mobileDirectory",
+      "type": "boolean",
+      "default": "true",
+      "description": "宽度不超过 900px 时自动进入全局 AppleSpeedDial 目录；设为 false 保持原位。没有宿主时保持原位。多个目录使用 AppleTabBar 切换，label 作为标签。"
+    },
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "items",
+      "type": "AppleTreeItem[]",
+      "default": "[]",
+      "description": "树节点为 { label: string; value: string | number; disabled?: boolean; description?: string; href?: string; content?: string } & { children?: AppleTreeItem[] }；value 在整棵树中应唯一。"
+    },
+    {
+      "name": "modelValue",
+      "type": "string | number",
+      "default": "undefined",
+      "description": "选中叶节点的 value；点击父节点只切换展开。折叠后可将高亮显示到最近可见祖先，原选择仍保留。"
+    },
+    {
+      "name": "expanded",
+      "type": "(string | number)[]",
+      "default": "undefined",
+      "description": "展开节点 value 的数组，可用 v-model:expanded；省略时内部管理。"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "default": "false",
+      "description": "禁用控件的交互。选项自身的 disabled 仍然独立生效。"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "default": "\"树形列表\"",
+      "description": "控件名称或区域的可访问名称。无可见名称时应提供 aria-label。"
+    }
+  ],
+  "events": [
+    {
+      "name": "update:modelValue",
+      "type": "(value: string | number) => void",
+      "description": "交互更新时发出新模型值；可使用 v-model 接收。"
+    },
+    {
+      "name": "update:expanded",
+      "type": "(value: (string | number)[]) => void",
+      "description": "交互更新 expanded 时发出新值；可使用对应的命名 v-model 接收。"
+    },
+    {
+      "name": "select",
+      "type": "(item: AppleTreeItem) => void",
+      "description": "选择可用叶节点时发出完整节点；父节点点击仅切换 expanded。"
+    }
+  ],
+  "slots": [
+    {
+      "name": "item",
+      "type": "({ item: AppleTreeItem, expanded: boolean, selected: boolean }) => VNode[]",
+      "description": "替代节点行的文字，不替代节点的展开和键盘处理。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "方向键、Home/End、Enter/空格可操作树。父节点只展开/折叠，选择事件只来自叶节点；没有复选框级联。"
+  ]
+})

package/templates/playground/src/editor/handbooks/apple-upload.ts

@@ -0,0 +1,126 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleUpload",
+  "source": "src/components/forms.ts",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "default": "\"\"",
+      "description": "控件名称或区域的可访问名称。无可见名称时应提供 aria-label。"
+    },
+    {
+      "name": "hint",
+      "type": "string",
+      "default": "\"\"",
+      "description": "字段帮助文字；error 非空时优先显示错误，帮助文字暂时隐藏。"
+    },
+    {
+      "name": "error",
+      "type": "string",
+      "default": "\"\"",
+      "description": "显示字段错误和错误样式，不会自行执行校验或阻止表单提交。"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "default": "false",
+      "description": "禁用控件的交互。选项自身的 disabled 仍然独立生效。"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "default": "false",
+      "description": "显示忙碌状态；表单控件在加载时禁止编辑或选择。"
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "default": "false",
+      "description": "为字段添加必填标记并传递必填约束；不会自动生成 error 文本。"
+    },
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "modelValue",
+      "type": "File[]",
+      "default": "[]",
+      "description": "浏览器 File 对象数组，不是 URL 或文件名数组。组件只选择文件，不发送网络请求。"
+    },
+    {
+      "name": "accept",
+      "type": "string",
+      "default": "\"\"",
+      "description": "允许的扩展名或 MIME 类型，逗号分隔，例如 .png,image/jpeg,image/*；选择和拖放都会检查。"
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "default": "false",
+      "description": "允许多个文件；开启时保留既有文件并追加，关闭时本次选择替换原数组。"
+    },
+    {
+      "name": "maxSize",
+      "type": "number",
+      "default": "Infinity",
+      "description": "单个文件大小上限，单位字节。默认 Infinity；超限通过 reject 返回。"
+    },
+    {
+      "name": "maxFiles",
+      "type": "number",
+      "default": "Infinity",
+      "description": "文件数量上限。multiple=false 时实际最多一个；重复文件会跳过。"
+    },
+    {
+      "name": "capture",
+      "type": "'user' | 'environment'",
+      "default": "undefined",
+      "description": "原生 file 输入的移动设备采集提示：user 或 environment，是否生效由浏览器决定。"
+    },
+    {
+      "name": "buttonText",
+      "type": "string",
+      "default": "\"选择文件\"",
+      "description": "文件选择区域的操作文字。"
+    }
+  ],
+  "events": [
+    {
+      "name": "update:modelValue",
+      "type": "(value: File[]) => void",
+      "description": "交互更新时发出新模型值；可使用 v-model 接收。"
+    },
+    {
+      "name": "change",
+      "type": "(value: File[]) => void",
+      "description": "用户提交选择或调整时发出当前值；直接从父组件赋值不会主动发出此事件。"
+    },
+    {
+      "name": "reject",
+      "type": "(rejections: { file: File; reason: string }[]) => void",
+      "description": "返回本次未通过类型、大小或数量检查的文件及原因。"
+    },
+    {
+      "name": "remove",
+      "type": "(file: File) => void",
+      "description": "移除单个文件时，在模型更新和 change 之后发出被移除的 File。"
+    }
+  ],
+  "slots": [
+    {
+      "name": "default",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "追加到文件选择区域中的内容；插槽内按钮保留自身操作。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "选中数据是本地 File[]。上传请求由应用实现；示例只记录文件选择与拒绝结果。",
+    "字段名称、帮助和错误文字只用于说明。直接操作控件；原生 name、autocomplete 等属性需按实际输入类型使用。"
+  ]
+})

package/templates/playground/src/editor/playground-examples.ts

@@ -0,0 +1,105 @@
+export interface SlotExample { scope?: string; code: string; enabled?: boolean }
+export interface PlaygroundExample {
+  props?: Record<string, string>
+  slots?: Record<string, SlotExample>
+  before?: string
+  actions?: { label: string; expression: string }[]
+}
+
+const options = JSON.stringify([{ label: '第一项', value: 'first' }, { label: '第二项', value: 'second' }, { label: '不可用', value: 'disabled', disabled: true }])
+const content = '<p>这里是组件内容。</p>'
+const blocks = '<div v-for="n in 3" :key="n" class="tile">{{ n }}</div>'
+const actions = JSON.stringify([{ label: '收藏', value: 'favorite' }, { label: '分享', value: 'share' }, { label: '删除', value: 'delete', danger: true }, { label: '不可用', value: 'disabled', disabled: true }])
+const image = (color: string, text: string) => 'data:image/svg+xml,' + encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" width="640" height="480"><rect width="640" height="480" fill="${color}"/><text x="320" y="260" fill="white" text-anchor="middle" font-size="64" font-family="sans-serif">${text}</text></svg>`)
+const gallery = JSON.stringify([{ src: image('#0071e3', 'Apptify'), alt: '蓝色示例图片', label: '蓝色' }, { src: image('#bf5af2', 'Vue'), alt: '紫色示例图片', label: '紫色' }, { src: image('#34c759', 'Hello'), alt: '绿色示例图片', label: '绿色' }])
+const scroll = '<div id="demo-scroll" class="scroll-demo" tabindex="0" aria-label="滚动示例"><div style="height: 900px">向下滚动，体验回到顶部。</div></div>'
+
+const examples: Record<string, PlaygroundExample> = {
+  AppleScrollBar: { props: { target: '"#demo-scroll"' }, before: '<div id="demo-scroll" class="scroll-demo" tabindex="0" aria-label="滚动示例"><div style="width: 760px; height: 900px; display: grid; gap: 16px"><div v-for="n in 12" :key="n" class="tile">{{ n }}</div></div></div>' },
+  AppleButton: { slots: { default: { code: '继续', enabled: true } } },
+  AppleLink: { props: { as: '"button"' }, slots: { default: { code: '了解更多', enabled: true } } },
+  AppleProvider: { props: { theme: '"dark"' }, slots: { default: { code: '<AppleInput v-model="fieldValue" label="局部主题" /><AppleButton @click="record(\'click\')">继续</AppleButton>', enabled: true } } },
+  AppleContainer: { props: { width: '360' }, slots: { default: { code: blocks, enabled: true } } },
+  AppleStack: { props: { direction: '"row"' }, slots: { default: { code: blocks, enabled: true } } },
+  AppleGrid: { props: { min: '120' }, slots: { default: { code: blocks, enabled: true } } },
+  AppleCard: { props: { title: '"Apptify"', subtitle: '"组件文档"', text: '"修改配置，体验卡片。"', image: JSON.stringify(image('#0071e3', 'Apptify')), imageAlt: '"蓝色示例图片"' } },
+  AppleImage: { props: { gallery, index: '0' }, slots: { item: { scope: '{ item, index, active }', code: '<div class="tile">{{ index + 1 }} · {{ item.label }} · {{ active }}</div>' } } },
+  AppleSearch: { props: { modelValue: '"Apptify"' } },
+  AppleTextarea: { props: { label: '"个人简介"', modelValue: '"写下你的想法。"', maxlength: '160', counter: 'true' } },
+  AppleSelect: { props: { label: '"选择项目"', items: options, modelValue: '"first"' } },
+  AppleAutocomplete: { props: { label: '"搜索项目"', items: options, modelValue: 'null' } },
+  AppleCheckbox: { props: { label: '"同意接收更新"' } },
+  AppleSwitch: { props: { label: '"接收通知"' } },
+  AppleRadioGroup: { props: { label: '"配送方式"', items: options, modelValue: '"first"' } },
+  AppleSegmentedControl: { props: { label: '"统计周期"', items: options, modelValue: '"first"' } },
+  AppleSlider: { props: { label: '"音量"', modelValue: '40' } },
+  AppleStepper: { props: { label: '"数量"', modelValue: '2', min: '0', max: '10' } },
+  AppleDatePicker: { props: { label: '"到店日期"', modelValue: '"2026-10-09"' } },
+  AppleColorPicker: { props: { label: '"强调色"' } },
+  AppleUpload: { props: { label: '"选择文件"', multiple: 'true', maxFiles: '3', maxSize: '5242880' } },
+  AppleOtpInput: { props: { modelValue: '""' } },
+  AppleCascader: { props: { label: '"所在地区"', items: JSON.stringify([{ label: '华东', value: 'east', children: [{ label: '上海', value: 'shanghai' }, { label: '杭州', value: 'hangzhou' }] }, { label: '华南', value: 'south', children: [{ label: '深圳', value: 'shenzhen' }] }]), levelLabels: '["地区", "城市"]' } },
+  AppleRate: { props: { modelValue: '3' } },
+  AppleForm: { props: { validator: '(data) => data.get("name") ? true : "请输入姓名"' }, slots: { default: { scope: '{ loading }', code: '<AppleInput v-model="fieldValue" name="name" label="姓名" required @keydown.enter.prevent="$refs.demo.submit()" /><AppleButton :loading="loading" @click="$refs.demo.submit()">提交</AppleButton><AppleLink as="button" @click="$refs.demo.reset()">重置</AppleLink>', enabled: true } } },
+  AppleFormField: { props: { label: '"个人网站"', hint: '"输入你的主页地址"' }, slots: { default: { scope: 'field', code: '<input v-bind="field" v-model="fieldValue" class="apple-control" type="url" placeholder="https://example.com" />', enabled: true } } },
+  AppleNavibar: { props: { brand: '"Apptify"', brandHref: '"#"', fixed: 'false', items: options, modelValue: '"first"' } },
+  AppleAside: { slots: { default: { code: '<p>侧栏导航</p>' + blocks, enabled: true } } },
+  AppleTabs: { props: { items: options, modelValue: '"first"' }, slots: { default: { scope: '{ item, value }', code: '<p>{{ item?.label }} · {{ value }}</p>', enabled: true } } },
+  AppleTabBar: { props: { items: options, modelValue: '"first"' }, slots: { default: { scope: '{ item, value }', code: '<p>{{ item?.label }} · {{ value }}</p>', enabled: true } } },
+  AppleBreadcrumbs: { props: { items: '[{"label":"首页","value":"home"},{"label":"组件","value":"components"},{"label":"当前页","value":"current"}]' } },
+  ApplePagination: { props: { total: '120' } },
+  AppleSteps: { props: { items: options, clickable: 'true' } },
+  AppleAccordion: { props: { items: '[{"label":"如何使用？","value":"first","content":"从 apptify 导入组件。"},{"label":"支持键盘吗？","value":"second","content":"按钮可以用 Enter 或空格操作。"}]' } },
+  AppleTable: { props: { columns: '[{"key":"name","label":"姓名","sortable":true},{"key":"score","label":"评分","sortable":true,"align":"right"}]', rows: '[{"id":1,"name":"林初","score":92},{"id":2,"name":"Alex","score":85},{"id":3,"name":"Taylor","score":97},{"id":4,"name":"Sam","score":88}]', selectable: 'true', pageSize: '3' } },
+  AppleTree: { props: { items: '[{"label":"文档","value":"docs","children":[{"label":"指南","value":"guide"},{"label":"API","value":"api"}]},{"label":"设置","value":"settings"}]', expanded: '["docs"]', mobileDirectory: 'false' } },
+  AppleList: { props: { items: options, selectable: 'true', modelValue: '"first"' } },
+  AppleAvatar: { props: { name: '"林初"', size: '48' } },
+  AppleAvatarGroup: { props: { items: '[{"name":"林初"},{"name":"Alex"},{"name":"Taylor"},{"name":"Sam"},{"name":"陈安"}]' } },
+  AppleBadge: { props: { value: '8' }, slots: { default: { code: '<AppleButton @click="props.value = Number(props.value || 0) + 1">消息</AppleButton>', enabled: true } } },
+  AppleTag: { props: { label: '"设计系统"', closable: 'true' } },
+  AppleAlert: { props: { title: '"保存成功"', message: '"内容已同步。"', closable: 'true' } },
+  AppleProgress: { props: { modelValue: '68', showValue: 'true' } },
+  AppleSpinner: {}, AppleSkeleton: {},
+  AppleEmpty: { props: { title: '"还没有收藏"', description: '"收藏的内容会出现在这里。"' } },
+  AppleDivider: { props: { label: '"更多选择"' } },
+  AppleTimeline: { props: { items: '[{"label":"已创建","value":"created","time":"09:00","description":"订单已创建。"},{"label":"已完成","value":"done","time":"10:00","tone":"success","description":"订单已完成。"}]' } },
+  AppleStatistic: { props: { label: '"本月访问"', value: '12840', suffix: '"次"' } },
+  AppleDialog: { props: { title: '"保存更改？"', message: '"你的更改会同步到所有设备。"' } },
+  AppleDrawer: { props: { title: '"偏好设置"', message: '"修改配置后再次打开体验。"' } },
+  AppleSheet: { props: { title: '"分享"', message: '"选择分享方式。"' } },
+  AppleSnackbar: { props: { message: '"内容已保存。"', duration: '0', action: '"撤销"' } },
+  ApplePopover: { slots: { default: { scope: '{ close }', code: '<p>面板内容</p><AppleButton @click="close()">完成</AppleButton>', enabled: true } } },
+  AppleTooltip: { props: { text: '"添加到收藏"' }, slots: { default: { scope: '{ props: triggerProps }', code: '<AppleButton v-bind="triggerProps">收藏</AppleButton>', enabled: true } } },
+  AppleMenu: { props: { items: actions } },
+  AppleActionSheet: { props: { title: '"选择操作"', items: actions } },
+  ApplePullRefresh: { slots: { default: { scope: '{ refreshing }', code: '<p>{{ refreshing ? \'正在刷新…\' : \'内容已就绪\' }} · {{ batches }} 次刷新</p>', enabled: true } } },
+  AppleInfiniteScroll: { slots: { default: { code: '<p v-for="n in batches" :key="n" class="tile">已加载第 {{ n }} 批</p>', enabled: true } } },
+  AppleBackTop: { props: { target: '"#demo-scroll"', threshold: '120', fixed: 'false' }, before: scroll },
+  AppleFloatingGroup: { props: { target: '"#demo-scroll"', threshold: '120' }, before: scroll, slots: { default: { code: '<AppleButton @click="record(\'action\')">帮助</AppleButton>', enabled: true } } },
+  AppleSpeedDial: { props: { target: '"#demo-scroll"', threshold: '120' }, before: scroll + '<AppleTree label="示例目录" :items="[{ label: \'概览\', value: \'overview\' }]" /><AppleSpeedDialItem label="新增" @click="record(\'create\')" />' },
+  AppleSpeedDialItem: { props: { label: '"新增"' }, before: '<AppleSpeedDial :threshold="0" />' },
+  AppleAutoSize: { before: '<AppleLink as="button" @click="expanded = !expanded">切换内容</AppleLink>', slots: { default: { code: '<div class="tile"><p>内容</p><p v-if="expanded">更多内容<br />更多内容<br />更多内容</p></div>', enabled: true } } },
+  AppleTransition: { before: '<AppleLink as="button" @click="expanded = !expanded">切换内容</AppleLink>', slots: { default: { code: '<div :key="String(expanded)" class="tile">{{ expanded ? \'第二页\' : \'第一页\' }}</div>', enabled: true } } },
+  AppleOverlayHost: { before: '<AppleButton @click="$apple.notify(\'内容已保存\', { tone: \'success\' })">显示通知</AppleButton><AppleButton variant="secondary" @click="$apple.dialog({ title: \'宿主对话框\', message: \'由 OverlayHost 渲染\' })">打开对话框</AppleButton>' },
+}
+
+export function playgroundExample(name: string): PlaygroundExample { return examples[name] || {} }
+
+export function slotExample(component: string, name: string): SlotExample {
+  const explicit = examples[component]?.slots?.[name]
+  if (explicit) return explicit
+  if (name === 'activator') return { scope: '{ props: triggerProps }', code: '<AppleButton v-bind="triggerProps">打开面板</AppleButton>' }
+  if (name === 'footer') return { scope: '{ close, confirm, cancel }', code: '<AppleButton @click="confirm()">确定</AppleButton><AppleLink as="button" @click="cancel()">取消</AppleLink>' }
+  if (name.startsWith('cell-')) return { scope: '{ row, value, index }', code: '<strong>{{ value }}</strong>' }
+  if (name.startsWith('panel-')) return { scope: '{ item }', code: '<p>{{ item?.label }}</p>' }
+  if (name.startsWith('item')) {
+    const scope = component === 'AppleTree' ? '{ item, expanded, selected }' : component === 'AppleList' ? '{ item, selected }' : component === 'AppleAccordion' ? '{ item, open }' : '{ item }'
+    return { scope, code: '<strong>{{ item.label }}</strong>' }
+  }
+  if (name === 'icon') return { code: '<Star :size="32" />' }
+  if (name === 'media') return { code: '<div class="tile">自定义媒体</div>' }
+  if (name === 'actions') return { scope: component === 'AppleNavibar' ? '{ close }' : undefined, code: '<AppleButton @click="record(\'action\')">操作</AppleButton>' }
+  if (name === 'default' && ['AppleDialog', 'AppleDrawer', 'AppleSheet'].includes(component)) return { scope: '{ close }', code: '<p>自定义正文</p><AppleButton @click="close(\'done\')">完成</AppleButton>' }
+  if (name === 'default' && component === 'AppleActionSheet') return { scope: '{ select, close }', code: '<AppleButton @click="select({ label: \'收藏\', value: \'favorite\' })">收藏</AppleButton>' }
+  return { code: content }
+}

package/templates/playground/src/images.ts

@@ -0,0 +1,3 @@
+export function imageUrl(filename: string) {
+  return `${import.meta.env.BASE_URL}images/${filename}`
+}

package/templates/playground/src/router/index.ts

@@ -1,24 +1,41 @@
 import { createRouter, createWebHistory } from 'vue-router'
 import routes from 'virtual:generated-pages'
 import { nextTick } from 'vue'
+import { cancelMotionScroll, scrollToWithMotion } from 'apptify'
+import { componentDocuments } from '../editor/documents'
 
 const router = createRouter({
   history: createWebHistory(import.meta.env.BASE_URL),
   routes,
   async scrollBehavior(to, from, savedPosition) {
     await nextTick()
+    if (to.path === '/components' && to.hash && to.path !== from.path) {
+      await new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+      await Promise.allSettled(document.getAnimations().filter(animation =>
+        Number.isFinite(Number(animation.effect?.getComputedTiming().endTime)),
+      ).map(animation => animation.finished))
+      await new Promise<void>(resolve => requestAnimationFrame(() => resolve()))
+    }
     if (savedPosition) return { ...savedPosition, behavior: 'instant' }
     if (to.hash && document.getElementById(to.hash.slice(1))) {
       const motion = document.querySelector('#app > .apple-provider')?.getAttribute('data-apple-motion')
-      return { el: to.hash, top: 96, behavior: to.path === from.path && motion === 'full' ? 'smooth' : 'instant' }
+      if (motion !== 'full') return { el: to.hash, top: 96, behavior: 'instant' }
+      if (router.currentRoute.value !== to) return false
+      const target = document.getElementById(to.hash.slice(1))!
+      const top = () => Math.min(target.getBoundingClientRect().top + window.scrollY - 96, Math.max(0, document.documentElement.scrollHeight - window.innerHeight))
+      await scrollToWithMotion(window, top).finished
+      return false
     }
     return { top: 0, behavior: 'instant' }
   },
 })
 
+router.beforeEach(() => { cancelMotionScroll(window) })
+
 router.afterEach(to => {
   const titles: Record<string, string> = { '/': '首页', '/components': '组件', '/settings': '设置' }
-  document.title = `${titles[to.path] ?? '页面不存在'} · Apptify`
+  const handbook = to.path.startsWith('/component-docs/') ? componentDocuments[String(to.params.component)] : undefined
+  document.title = `${handbook ? `${handbook.label} ${handbook.name}` : to.meta.title ?? titles[to.path] ?? '页面不存在'} · Apptify`
 })
 
 export default router

package/templates/playground/src/style.css

@@ -16,7 +16,7 @@ button { font: inherit; }
 .brand { display: inline-flex; align-items: center; gap: 10px; color: var(--apple-text); text-decoration: none; font-weight: 650; font-size: 20px; }
 .brand-symbol { width: 28px; height: 28px; border-radius: 8px; display: grid; place-items: center; background: var(--apple-text); color: var(--apple-surface); font-weight: 600; font-size: 24px; line-height: 1; padding-bottom: 4px; font-family: Georgia,serif; }
 .user-trigger { width: 38px; height: 38px; border: 1px solid var(--apple-border); border-radius: 50%; display: grid; place-items: center; background: var(--apple-surface); color: var(--apple-text); transition: background var(--apple-fast); }
-.user-trigger:hover:where(:not([data-apple-touch] *)),.user-trigger[aria-expanded=true] { background: var(--apple-selected); }
+.user-trigger:hover,.user-trigger[aria-expanded=true] { background: var(--apple-selected); }
 .user-popup.apple-popover { padding: 8px; }
 .user-summary { display: flex; align-items: center; gap: 12px; padding: 14px 10px 20px; }
 .user-summary > div { min-width: 0; }
@@ -25,7 +25,7 @@ button { font: inherit; }
 .user-summary > div > span { display: block; color: var(--apple-secondary); font-size: 11px; margin-top: 4px; overflow-wrap: anywhere; }
 .user-menu-list { border-top: 1px solid var(--apple-border); padding: 6px 0; }
 .user-menu-list > :is(button,a) { display: flex; align-items: center; gap: 11px; width: 100%; padding: 12px 10px; border: 0; border-radius: 6px; background: transparent; color: var(--apple-text); font-size: 13px; text-align: left; text-decoration: none; }
-.user-menu-list > :is(button,a):hover:where(:not([data-apple-touch] *)) { background: var(--apple-hover); }
+.user-menu-list > :is(button,a):hover { background: var(--apple-hover); }
 .user-menu-list > :is(button,a):active { background: var(--apple-pressed); }
 .user-menu-list span { flex: 1; }
 .user-menu-list svg,.user-menu-list small { color: var(--apple-secondary); }
@@ -91,8 +91,8 @@ button { font: inherit; }
 
 .specimen > .apple-card__body > .apple-search { margin-bottom: 12px; }
 .directory-layout { display: grid; grid-template-columns: 224px minmax(0, 1fr); gap: 32px; align-items: start; }
-.directory-index { position: sticky; top: 100px; max-height: calc(100dvh - 120px); overflow: auto; overscroll-behavior: contain; scrollbar-width: thin; padding-top: 16px; font-size: 13px; min-width: 0; }
-.directory-index > span { color: var(--apple-secondary); font-size: 12px; display: block; margin: 0 0 12px 8px; }
+.directory-index { position: sticky; top: 100px; display: flex; flex-direction: column; max-height: calc(100dvh - 120px); overflow: hidden; padding-top: 16px; font-size: 13px; min-width: 0; }
+.directory-index > span { flex-shrink: 0; color: var(--apple-secondary); font-size: 12px; display: block; margin: 0 0 12px 8px; }
 .directory-index .apple-tree__row { min-height: 34px; }
 .directory-index .apple-tree__row > span:last-child { min-width: 0; overflow-wrap: anywhere; }
 .components-page { padding: 40px 40px 0; }

package/templates/playground/src/views/403.vue

@@ -0,0 +1,65 @@
+<template>
+  <main class="main-content paper-403-page">
+    <apple-card class="paper-403-card" shadow="none" zoom="none">
+      <template #title>
+        <div class="paper-403-heading">
+          <p class="paper-403-number" aria-hidden="true">403</p>
+          <h1>无权访问</h1>
+        </div>
+      </template>
+      <p class="paper-403-copy">这只鸡腿，可不能随便拿。<br />你暂时没有访问此页面的权限。</p>
+      <div class="paper-403-actions">
+        <router-link v-slot="{ href, navigate }" :to="homePath" custom>
+          <apple-button :href="href" @click="navigate">返回首页</apple-button>
+        </router-link>
+        <apple-link as="button" @click="goBack"><ArrowLeft :size="16" aria-hidden="true" /> 返回上一页</apple-link>
+      </div>
+    </apple-card>
+    <ForbiddenPaperScene class="paper-403-illustration" />
+  </main>
+</template>
+
+<route lang="json">
+{ "alias": "/error/403", "meta": { "title": "无权访问" } }
+</route>
+
+<script setup lang="ts">
+import { ArrowLeft } from 'lucide-vue-next'
+import { useRouter } from 'vue-router'
+import ForbiddenPaperScene from '../components/forbidden-paper-scene.vue'
+
+const router = useRouter()
+const homePath = router.getRoutes().some(page => page.path === '/') ? '/' : '/settings'
+function goBack() {
+  if (typeof router.options.history.state.back === 'string') router.back()
+  else void router.push(homePath)
+}
+</script>
+
+<style scoped>
+.paper-403-page { max-width: 1360px; display: grid; grid-template-columns: minmax(260px, .78fr) minmax(0, 1.65fr); align-content: center; align-items: center; column-gap: 16px; padding-top: 38px; padding-bottom: calc(38px + 64px); }
+.paper-403-card { background: transparent; border: 0; overflow: visible; }
+.paper-403-card :deep(.apple-card__body) { padding: 0 0 0 8px; }
+.paper-403-card :deep(.apple-card__heading) { margin: 0; }
+.paper-403-heading { width: 100%; }
+.paper-403-number { color: var(--apple-text); font-family: Georgia, 'Times New Roman', serif; font-size: clamp(78px, 8.2vw, 118px); line-height: .9; letter-spacing: -.075em; margin: 0 0 28px; font-weight: 400; }
+.paper-403-heading h1 { font-size: clamp(26px, 2.7vw, 35px); line-height: 1.35; letter-spacing: -.035em; font-weight: 600; margin: 0 0 17px; }
+.paper-403-copy { font-size: 13px; line-height: 1.95; color: var(--apple-secondary); margin: 0; text-wrap: pretty; }
+.paper-403-actions { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; margin-top: 27px; }
+.paper-403-actions .apple-link { font-size: 12px; padding-inline: 8px; color: var(--apple-secondary); }
+.paper-403-illustration { min-width: 0; }
+@media (max-width: 880px) {
+  .paper-403-page { grid-template-columns: minmax(0, 1fr); max-width: 680px; padding-top: 18px; }
+  .paper-403-illustration { grid-row: 1; }
+  .paper-403-card { margin-top: 26px; }
+  .paper-403-card :deep(.apple-card__body) { padding: 0; text-align: center; }
+  .paper-403-number { font-size: 70px; margin-bottom: 18px; }
+  .paper-403-heading h1 { font-size: 26px; margin-bottom: 12px; }
+  .paper-403-actions { justify-content: center; margin-top: 18px; }
+}
+@media (max-width: 420px) {
+  .paper-403-page { padding-inline: 18px; padding-top: 12px; }
+  .paper-403-copy { font-size: 12px; }
+  .paper-403-card { margin-top: 22px; }
+}
+</style>

package/templates/playground/src/views/component-docs/[component].vue

@@ -6,28 +6,26 @@
       <div class="documentation-layout directory-layout">
         <aside ref="documentationIndex" class="documentation-index directory-index" aria-label="API 导航"><span>本页接口</span><apple-tree v-model="selectedApi" v-model:expanded="expandedSections" :items="apiTree" label="组件 API 树" @select="navigateApi" /></aside>
         <div ref="documentationContent" class="documentation-content">
-          <section class="component-overview" aria-label="组件演示"><component :is="registration.preview" v-if="registration.preview" /></section>
-          <ComponentWorkshop v-if="doc" :doc="doc" />
+          <section class="component-overview" aria-label="组件演示"><component :is="registration.preview" v-if="registration.preview" /><ComponentPlayground v-else-if="doc" :key="doc.name" :doc="doc" /></section>
+          <ComponentWorkshop v-if="doc" :key="doc.name" :doc="doc" />
           <apple-alert v-else-if="failed" tone="danger" title="文档加载失败"><apple-button variant="secondary" @click="loadDocument">重试</apple-button></apple-alert>
           <apple-spinner v-else label="正在加载组件 API" />
         </div>
       </div>
     </template>
-    <apple-empty v-else title="组件文档尚未开放" description="当前阶段仅开放 AppleInput 样板。"><router-link to="/components" custom v-slot="{ href, navigate }"><apple-link :href="href" @click="navigate">返回组件目录</apple-link></router-link></apple-empty>
+    <apple-empty v-else title="未找到组件文档"><router-link to="/components" custom v-slot="{ href, navigate }"><apple-link :href="href" @click="navigate">返回组件目录</apple-link></router-link></apple-empty>
   </apple-container>
-  <DirectoryDialog v-if="registration" v-model="mobileIndex" title="本页接口">
-    <apple-tree v-model="selectedApi" v-model:expanded="expandedSections" :items="apiTree" label="组件 API 树" @select="navigateApi" />
-  </DirectoryDialog>
 </template>
 <script setup lang="ts">
-import { computed, shallowRef, ref, watch, onMounted, onBeforeUnmount, nextTick } from 'vue'
+defineOptions({ inheritAttrs: false })
+import { computed, defineAsyncComponent, shallowRef, ref, watch, onMounted, onBeforeUnmount, nextTick } from 'vue'
 import { useRoute, useRouter } from 'vue-router'
 import type { AppleItem, AppleTreeItem, AppleValue } from 'apptify'
 import { componentDocuments } from '../../editor/documents'
 import type { ComponentDocument } from '../../editor/contract'
 import { documentSections } from '../../editor/sections'
 import ComponentWorkshop from '../../editor/ComponentWorkshop.vue'
-import DirectoryDialog from '../../components/DirectoryDialog.vue'
+const ComponentPlayground = defineAsyncComponent(() => import('../../editor/ComponentPlayground.vue'))
 const route = useRoute()
 const router = useRouter()
 const breadcrumbs = computed(() => [
@@ -56,7 +54,6 @@ watch(registration, loadDocument, { immediate: true })
 onBeforeUnmount(() => { loadVersion++ })
 const documentationIndex = ref<HTMLElement>()
 const documentationContent = ref<HTMLElement>()
-const mobileIndex = ref(false)
 const selectedApi = ref<AppleValue>('props')
 const expandedSections = ref<AppleValue[]>(['props', 'events', 'slots', 'methods'])
 const apiTree = computed<AppleTreeItem[]>(() => doc.value ? [
@@ -105,10 +102,11 @@ function queueScrollSelection() {
 function revealSelection() {
   const index = documentationIndex.value
   const row = index?.querySelector<HTMLElement>('.apple-tree__row.is-selected')
-  if (!index || !row) return
-  const bounds = index.getBoundingClientRect(), selected = row.getBoundingClientRect()
-  if (selected.top < bounds.top) index.scrollTop += selected.top - bounds.top
-  else if (selected.bottom > bounds.bottom) index.scrollTop += selected.bottom - bounds.bottom
+  const scroll = index?.querySelector<HTMLElement>('.apple-tree-scroll')
+  if (!scroll || !row) return
+  const bounds = scroll.getBoundingClientRect(), selected = row.getBoundingClientRect()
+  if (selected.top < bounds.top) scroll.scrollTop += selected.top - bounds.top
+  else if (selected.bottom > bounds.bottom) scroll.scrollTop += selected.bottom - bounds.bottom
 }
 watch([selectedApi, expandedSections], async () => {
   await nextTick()
@@ -140,7 +138,6 @@ onBeforeUnmount(() => {
 
 async function navigateApi(item: AppleTreeItem) {
   if (item.children?.length) return
-  mobileIndex.value = false
   const id = String(item.value)
   await nextTick()
   await router.replace({ hash: `#${id}` })