apptify 0.5.0 → 0.5.4

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}`

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

@@ -0,0 +1,59 @@
+import { icons } from 'lucide-vue-next'
+import exampleSource from './AppleInputExample.vue?raw'
+
+export function createInputConfig() {
+  return {
+    type: 'text', label: '姓名', placeholder: '怎么称呼你', hint: '用于在应用中显示你的名称。', error: '',
+    clearable: true, disabled: false, loading: false, required: false,
+    prefixMode: 'none', prefix: '', prefixIcon: 'Mail', suffixMode: 'none', suffix: '', suffixIcon: 'Search', motion: 'inherit' as 'inherit' | 'auto' | 'full' | 'reduced' | 'none',
+    name: 'name', ariaLabel: '', maxlength: '', autocomplete: 'off', min: '', max: '', step: '',
+  }
+}
+export type InputConfig = ReturnType<typeof createInputConfig>
+export function buildInputProps(config: InputConfig) {
+  return {
+    type: config.type, label: config.label, placeholder: config.placeholder, hint: config.hint, error: config.error,
+    clearable: config.clearable, disabled: config.disabled, loading: config.loading, required: config.required,
+    motion: config.motion, name: config.name || undefined,
+    'aria-label': config.ariaLabel || (!config.label ? '演示输入框' : undefined),
+    maxlength: config.maxlength !== '' && Number.isInteger(Number(config.maxlength)) && Number(config.maxlength) >= 0 ? Number(config.maxlength) : undefined,
+    autocomplete: config.autocomplete,
+    min: config.type === 'number' && config.min !== '' ? config.min : undefined,
+    max: config.type === 'number' && config.max !== '' ? config.max : undefined,
+    step: config.type === 'number' && Number(config.step) > 0 ? config.step : undefined,
+  }
+}
+const iconNames = new Map(Object.keys(icons).map(name => [name.toLowerCase(), name]))
+export function resolveIconName(code: string): string | undefined {
+  return iconNames.get(code.trim().replace(/-/g, '').toLowerCase())
+}
+export function iconCodeError(code: string): string {
+  return resolveIconName(code) ? '' : '请输入有效图标代号，例如 Mail、Search、ArrowRight。'
+}
+// This Vue source is both the editable file and the compiled preview.
+const literal = (value: unknown) => JSON.stringify(value).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029')
+const attribute = (value: string) => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+const text = (value: string) => attribute(value).replace(/{/g, '&#123;').replace(/}/g, '&#125;')
+export function generateInputCode(config: InputConfig, value: string | number) {
+  const attrs = Object.entries(buildInputProps(config)).flatMap(([name, next]) => {
+    if (next === undefined || next === '' || next === false) return []
+    return [typeof next === 'boolean' ? `          ${name}` : typeof next === 'number' ? `          :${name}="${next}"` : `          ${name}="${attribute(next)}"`]
+  }).join('\n')
+  const prefixIcon = config.prefixMode === 'icon' ? resolveIconName(config.prefixIcon) : undefined
+  const suffixIcon = config.suffixMode === 'icon' ? resolveIconName(config.suffixIcon) : undefined
+  const usedIcons = [...new Set([prefixIcon, suffixIcon].filter((name): name is string => !!name))]
+  const affix = (slot: string, mode: string, value: string, icon?: string) => {
+    if (mode === 'icon' && icon) return `<template #${slot}><${icon} :size="18" aria-hidden="true" /></template>`
+    return mode === 'text' ? `<template #${slot}><span>${text(value)}</span></template>` : ''
+  }
+  const prefix = affix('prefix', config.prefixMode, config.prefix, prefixIcon)
+  const suffix = affix('suffix', config.suffixMode, config.suffix, suffixIcon)
+  return exampleSource
+    .replace("import { Mail } from 'lucide-vue-next'", () => usedIcons.length ? `import { ${usedIcons.join(', ')} } from 'lucide-vue-next'` : '')
+    .replace(/, Mail(?= })/, () => usedIcons.length ? ', ' + usedIcons.join(', ') : '')
+    .replace("value: 'Apptify'", () => `value: ${literal(value)}`)
+    .replace(/(v-model="value"\n)[\s\S]*?(\n\s+@update:model-value)/, (_, start, end) => `${start}${attrs}${end}`)
+    .replace('<!-- prefix -->', () => prefix)
+    .replace('<!-- suffix -->', () => suffix)
+    .replace(':disabled="false"', () => config.disabled || config.loading ? 'disabled' : '')
+}

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

@@ -0,0 +1,5 @@
+import 'apptify/style.css'
+// Template packaging adapts this import to the public apptify package.
+export * from 'apptify'
+
+export * from 'lucide-vue-next'

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

@@ -0,0 +1,10 @@
+import type { ComponentDocument } from './contract'
+/** One section map drives both document content and its API navigation tree. */
+export function documentSections(doc: ComponentDocument) {
+  return [
+    { id: 'props', kicker: 'PROPS', title: '属性', entries: doc.props },
+    { id: 'events', kicker: 'EVENTS', title: '事件', entries: doc.events },
+    { id: 'slots', kicker: 'SLOTS', title: '插槽', entries: doc.slots },
+    { id: 'methods', kicker: 'METHODS', title: '公开方法', entries: doc.methods },
+  ].filter(section => section.entries.length)
+}

package/templates/playground/{playground → src}/style.css

@@ -5,6 +5,14 @@ button { font: inherit; }
 #app > .apple-provider { min-height: 100dvh; }
 .apple-auto-size__inner { position: relative; }
 .route-page { display: contents; }
+.site-footer { width: 100%; margin-inline: auto; margin-top: 16px; padding-inline: 48px; background: var(--apple-surface-alt); }
+.route-page:has(.components-page) + .site-footer > .page-footer { margin-inline: auto; }
+@media (max-width: 1100px) {
+  .site-footer { padding-inline: 28px; }
+}
+@media (max-width: 640px) {
+  .site-footer { padding-inline: 18px; }
+}
 .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); }
@@ -47,9 +55,10 @@ button { font: inherit; }
 .more-components { display: flex; align-items: center; justify-content: space-between; gap: 20px; padding: 38px 0; }
 .more-components h2 { margin: 0 0 8px; font-size: 19px; font-weight: 600; }
 .more-components span { font-size: 12px; color: var(--apple-secondary); }
-.page-footer { padding: 24px 0; border-top: 1px solid var(--apple-border); display: flex; justify-content: space-between; flex-wrap: wrap; gap: 12px; font-size: 11px; color: var(--apple-secondary); margin-top: 16px; }
+.page-footer { padding: 24px 0; border: 0; font-size: 12px; color: var(--apple-secondary); place-items: center; text-align: center }
 .specimen-grid { display: grid; grid-template-columns: 1.04fr 1fr 1fr; gap: 18px; }
-.specimen { min-width: 0; padding: 21px 24px 22px; border-radius: 8px; background: var(--apple-surface); box-shadow: 0 2px 10px rgb(0 0 0 / .025); position: relative; display: flex; flex-direction: column; }
+.specimen { min-width: 0; }
+.specimen > .apple-card__body { height: 100%; display: flex; flex-direction: column; padding: 9px 12px 10px; }
 .specimen-caption { display: flex; align-items: center; justify-content: space-between; color: var(--apple-secondary); font-size: 9px; margin-bottom: 22px; }
 .specimen h2 { font-size: 21px; font-weight: 600; line-height: 1.3; margin: 0 0 25px; }
 .button-specimens { display: flex; align-items: center; flex-direction: column; gap: 15px; padding: 9px 0 22px; }
@@ -62,10 +71,10 @@ button { font: inherit; }
 .preference-demo .apple-field__label { display: none; }
 .preference-demo .apple-slider .apple-field__label { display: block; }
 .setting-line { display: flex; align-items: center; justify-content: space-between; gap: 12px; border-bottom: 1px solid color-mix(in srgb,var(--apple-border) 55%,transparent); padding: 3px 0 13px; }
-.setting-line > div:first-child { min-width: 0; }
+.setting-line > div:first-child { flex: 1; min-width: 0; }
 .setting-line strong { display: block; font-size: 12px; font-weight: 500; }
 .setting-line small { display: block; font-size: 10px; color: var(--apple-secondary); margin-top: 4px; }
-.setting-line .apple-field { flex-shrink: 0; }
+.setting-line .apple-field { flex-shrink: 0; width: auto; }
 .check-row { padding-top: 5px; }
 .check-row .apple-choice__label { font-size: 11px; }
 .form-specimen .apple-form { display: flex; flex-direction: column; gap: 13px; }
@@ -80,33 +89,29 @@ button { font: inherit; }
 .feedback-actions { margin-top: auto; display: flex; flex-wrap: wrap; gap: 3px; padding-top: 25px; }
 .feedback-actions .apple-button { font-size: 11px; }
 
-.specimen > .apple-search { margin-bottom: 12px; }
-.sidebar { width: 232px; position: fixed; top: 64px; bottom: 0; left: 0; z-index: 40; padding: 30px 14px 24px; border-right: 1px solid color-mix(in srgb,var(--apple-border) 55%,transparent); background: var(--apple-surface); overflow-y: auto; overscroll-behavior: contain; scrollbar-width: thin; }
-.sidebar-heading { display: flex; flex-direction: column; gap: 7px; padding: 0 14px; margin-bottom: 24px; }
-.sidebar-heading strong { font-size: 13px; font-weight: 600; }
-.sidebar-heading > span { font-size: 10px; color: var(--apple-secondary); }
-.component-index a { text-decoration: none; color: var(--apple-secondary); font-size: 12px; }
-.index-group { display: flex; align-items: center; gap: 10px; padding: 11px 14px; border-radius: 6px; }
-.index-group span { flex: 1; }
-.index-group small { font-size: 10px; font-variant-numeric: tabular-nums; color: var(--apple-secondary); }
-.index-group.active { color: var(--apple-text); font-weight: 600; }
-.index-items { margin: 3px 0 12px 21px; padding-left: 12px; border-left: 1px solid var(--apple-border); }
-.index-items a { display: block; border-radius: 5px; padding: 7px 10px; }
-.component-index a:hover:where(:not([data-apple-touch] *)) { color: var(--apple-text); background: var(--apple-hover); }
-.index-items a.active { background: var(--apple-selected); color: var(--apple-text); font-weight: 500; }
-.components-page { margin-left: 232px; width: calc(100% - 232px); max-width: none; padding: 42px 48px 0; }
-.components-page > * { max-width: 1000px; margin-inline: auto; }
+.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 .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; }
+.components-content { min-width: 0; }
+@media (max-width: 900px) {
+  .directory-layout { grid-template-columns: minmax(0, 1fr); gap: 20px; }
+  .directory-index { display: none; }
+}
 .feed-toolbar { display: flex; justify-content: space-between; align-items: center; gap: 12px; padding-bottom: 14px; border-bottom: 1px solid var(--apple-border); }
 .feed-count { font-size: 12px; font-weight: 500; }
 .feed-count small { margin-left: 7px; color: var(--apple-secondary); font-size: 10px; font-variant-numeric: tabular-nums; }
 .preview-controls { display: flex; gap: 4px; }
-.mobile-index-toggle { display: none; }
 .feed-group { padding-bottom: 16px; }
 .feed-group-heading { display: flex; align-items: baseline; gap: 12px; padding: 32px 0 20px; }
 .feed-group-heading > span { color: var(--apple-secondary); font-size: 11px; font-variant-numeric: tabular-nums; }
 .feed-group-heading h2 { margin: 0; font-size: 20px; font-weight: 600; }
 .feed-group-heading small { margin-left: auto; font-size: 11px; color: var(--apple-secondary); }
-.component-card { min-width: 0; background: var(--apple-surface); border: 1px solid color-mix(in srgb,var(--apple-border) 40%,transparent); border-radius: 10px; margin-bottom: 20px; }
+.component-card { min-width: 0; margin-bottom: 20px; }
+.component-card > .apple-card__body { padding: 0; }
 .component-card-heading { display: flex; justify-content: space-between; align-items: flex-start; flex-wrap: wrap; gap: 12px; padding: 24px 28px 0; }
 .component-card-heading h3 { font-size: 16px; font-weight: 600; margin: 0; }
 .component-card-heading h3 a { display: inline-flex; align-items: center; gap: 8px; color: inherit; text-decoration: none; }
@@ -119,7 +124,6 @@ button { font: inherit; }
 .detail-preview .component-demo--compact { max-width: 420px; }
 .detail-preview .component-demo--media { max-width: 560px; }
 .detail-preview.mobile-preview { max-width: 390px; margin-inline: auto; }
-.component-card > .component-source { border-radius: 0 0 9px 9px; }
 .component-source { border-top: 1px solid color-mix(in srgb,var(--apple-border) 45%,transparent); }
 .code-view { padding: 4px 28px 20px; min-width: 0; }
 .code-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 16px; color: var(--apple-secondary); font-size: 12px; }
@@ -132,9 +136,10 @@ pre { padding: 18px; overflow: auto; background: var(--apple-surface-alt); borde
 .component-demo .apple-form__fields { gap: 20px; }
 .component-demo .apple-form__fields > .apple-button { justify-self: start; }
 .component-demo .apple-grid { align-items: start; }
-.demo-layout-tile { display: flex; flex-direction: column; justify-content: center; gap: 12px; min-height: 112px; padding: 20px; border: 1px solid var(--apple-border); border-radius: 10px; background: var(--apple-surface-alt); }
-.demo-layout-tile > span { color: var(--apple-secondary); font-size: 12px; font-variant-numeric: tabular-nums; }
-.demo-layout-tile > strong { font-size: 16px; font-weight: 550; }
+.demo-layout-tile { min-height: 112px; }
+.demo-layout-tile > .apple-card__body { display: flex; flex-direction: column; justify-content: center; gap: 12px; padding: 8px; }
+.demo-layout-tile > .apple-card__body > span { color: var(--apple-secondary); font-size: 12px; font-variant-numeric: tabular-nums; }
+.demo-layout-tile > .apple-card__body > strong { font-size: 16px; font-weight: 550; }
 .component-demo > .apple-stack > .apple-provider { border-radius: 10px; }
 .component-demo[data-component="AppleSpinner"] .apple-spinner { align-self: flex-start; }
 .component-demo[data-component="AppleDivider"] .apple-divider:not(.apple-divider--vertical) { width: 100%; }
@@ -150,10 +155,10 @@ pre { padding: 18px; overflow: auto; background: var(--apple-surface-alt); borde
 .demo-copy { margin: 0; padding: 8px 0; color: var(--apple-secondary); }
 .demo-slide { display: block; width: 100%; aspect-ratio: 16/10; object-fit: cover; }
 
-.demo-floating-preview { padding: 24px; border-radius: 8px; }
+.demo-floating-preview > .apple-card__body { padding: 12px; }
 .demo-floating-preview .apple-floating-group { position: relative; inset: auto; flex-direction: row; justify-content: center; padding: 12px 0; z-index: auto; }
-.settings-page { max-width: 980px; }
-.settings-section { background: var(--apple-surface); border: 1px solid color-mix(in srgb,var(--apple-border) 40%,transparent); border-radius: 12px; padding: 28px; margin-bottom: 22px; }
+.settings-section { margin-bottom: 22px; }
+.settings-section > .apple-card__body { padding: 16px; }
 .settings-section-heading { display: flex; align-items: flex-start; gap: 12px; margin-bottom: 26px; }
 .settings-section-heading > svg { margin-top: 3px; color: var(--apple-secondary); }
 .settings-section h2 { font-size: 19px; font-weight: 600; margin: 0; }
@@ -167,20 +172,16 @@ pre { padding: 18px; overflow: auto; background: var(--apple-surface-alt); borde
 .theme-swatch i:last-child { width: 35%; }
 .theme-label { display: flex; align-items: center; justify-content: space-between; gap: 4px; width: 100%; min-height: 20px; font-size: 12px; padding: 0 2px 3px; }
 .theme-label svg { color: var(--apple-accent); flex-shrink: 0; }
-.settings-section > .apple-segmented { max-width: 440px; }
+.settings-section > .apple-card__body > .apple-segmented { max-width: 440px; }
 .settings-note { color: var(--apple-secondary); font-size: 12px; line-height: 1.8; min-height: 22px; margin: 14px 0 24px; }
-.motion-preview { background: var(--apple-surface-alt); border-radius: 8px; padding: 14px 20px 22px; }
+.motion-preview > .apple-card__body { padding: 2px 8px 10px; }
 .motion-preview-heading { display: flex; justify-content: space-between; align-items: center; gap: 12px; font-size: 12px; color: var(--apple-secondary); margin-bottom: 14px; }
 .motion-preview-content p { margin: 18px 0 0; font-size: 13px; color: var(--apple-secondary); line-height: 1.8; }
 .settings-reset { display: flex; align-items: center; justify-content: space-between; gap: 12px; color: var(--apple-secondary); font-size: 12px; margin: 26px 0 48px; }
 .not-found-page { max-width: 740px; }
-@media (min-width: 1600px) { .main-content.home-page { max-width: 1420px; } .specimen-grid { gap: 24px; } .specimen { padding: 26px 30px; } }
-@media (max-width: 1100px) { .main-content { padding-inline: 28px; } .components-page { padding-inline: 32px; } .sidebar { width: 210px; } .components-page { margin-left: 210px; width: calc(100% - 210px); } .specimen-grid { grid-template-columns: 1fr 1fr; } }
+@media (min-width: 1600px) { .main-content.home-page { max-width: 1420px; } .specimen-grid { gap: 24px; } .specimen > .apple-card__body { padding: 14px 18px; } }
+@media (max-width: 1100px) { .main-content { padding-inline: 28px; } .components-page { padding-inline: 32px; } .specimen-grid { grid-template-columns: 1fr 1fr; } }
 @media (max-width: 800px) {
-  .sidebar { display: none; }
-  .components-page { margin-left: 0; width: 100%; }
-  .mobile-index-toggle { display: inline-flex; align-items: center; gap: 8px; min-height: 40px; padding: 0; border: 0; background: transparent; color: var(--apple-text); font-size: 12px; }
-  .feed-count { display: none; }
   .theme-options { gap: 8px; }
 }
 @media (max-width: 640px) {
@@ -198,7 +199,7 @@ pre { padding: 18px; overflow: auto; background: var(--apple-surface-alt); borde
   .mobile-break { display: block; }
   .section-heading { align-items: flex-start; flex-direction: column; gap: 7px; padding-top: 22px; }
   .specimen-grid { grid-template-columns: 1fr; gap: 16px; }
-  .specimen { padding: 24px; }
+  .specimen > .apple-card__body { padding: 12px; }
   .specimen h2 { font-size: 23px; }
   .specimen-caption { font-size: 10px; }
   .button-specimens > .apple-button { min-height: 44px; }
@@ -218,7 +219,7 @@ pre { padding: 18px; overflow: auto; background: var(--apple-surface-alt); borde
   .detail-preview { padding: 28px 16px; }
   .code-view { padding-inline: 16px; }
   pre { padding: 14px; font-size: 11px; }
-  .settings-section { padding: 22px 18px; }
+  .settings-section > .apple-card__body { padding: 10px 6px; }
   .theme-options { grid-template-columns: repeat(3,minmax(0,1fr)); gap: 12px; }
   .theme-swatch { height: 68px; padding: 12px; }
   .theme-label { font-size: 11px; }

package/templates/playground/{playground → src}/views/[...all].vue

@@ -12,7 +12,7 @@
         <router-link v-slot="{ href, navigate }" :to="homePath" custom>
           <apple-button :href="href" @click="navigate">返回首页</apple-button>
         </router-link>
-        <apple-button variant="ghost" @click="goBack"><ArrowLeft :size="16" aria-hidden="true" /> 返回上一页</apple-button>
+        <apple-link as="button" @click="goBack"><ArrowLeft :size="16" aria-hidden="true" /> 返回上一页</apple-link>
       </div>
     </apple-card>
     <NotFoundPaperScene class="paper-404-illustration" />
@@ -45,7 +45,7 @@ function goBack() {
 .paper-404-heading h1 { font-size: clamp(26px, 2.7vw, 35px); line-height: 1.35; letter-spacing: -.035em; font-weight: 600; margin: 0 0 17px; }
 .paper-404-copy { font-size: 13px; line-height: 1.95; color: var(--apple-secondary); margin: 0; text-wrap: pretty; }
 .paper-404-actions { display: flex; align-items: center; gap: 12px; flex-wrap: wrap; margin-top: 27px; }
-.paper-404-actions .apple-button--ghost { font-size: 12px; padding-inline: 8px; color: var(--apple-secondary); }
+.paper-404-actions .apple-link { font-size: 12px; padding-inline: 8px; color: var(--apple-secondary); }
 .paper-404-illustration { min-width: 0; }
 .paper-404-footnote { grid-column: 1 / -1; text-align: center; font-size: 10px; letter-spacing: .09em; color: var(--apple-secondary); margin: 48px 0 0; }
 @media (max-width: 880px) {

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

@@ -0,0 +1,162 @@
+<template>
+  <apple-container style="padding-top: 12px; padding-bottom: 24px">
+    <template v-if="registration">
+      <apple-breadcrumbs :items="breadcrumbs" label="组件文档路径" @click="navigateBreadcrumb" />
+      <header class="documentation-heading"><div><span class="page-kicker">{{ registration.group }} / COMPONENT API</span><h1>{{ registration.label }}<span>{{ registration.name }}</span></h1><p>{{ registration.description }}</p></div></header>
+      <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" />
+          <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-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'
+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 route = useRoute()
+const router = useRouter()
+const breadcrumbs = computed(() => [
+  { label: '组件', value: 'components', href: '/components' },
+  { label: registration.value?.group || '组件', value: 'group', href: `/components#${String(route.params.component)}` },
+  { label: registration.value?.label || '', value: 'current' },
+])
+function navigateBreadcrumb(item: AppleItem, event: MouseEvent) {
+  if (!item.href || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+  event.preventDefault()
+  void router.push(item.href)
+}
+const registration = computed(() => componentDocuments[String(route.params.component)])
+const doc = shallowRef<ComponentDocument>()
+const failed = ref(false)
+let loadVersion = 0
+async function loadDocument() {
+  const version = ++loadVersion
+  doc.value = undefined; failed.value = false
+  const current = registration.value
+  if (!current) return
+  try { const result = await current.load(); if (version === loadVersion) doc.value = result.default }
+  catch { if (version === loadVersion) failed.value = true }
+}
+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 ? [
+  ...documentSections(doc.value).map(section => ({
+    value: section.id, label: section.title,
+    children: section.entries.map(entry => ({ value: entry.id, label: entry.name })),
+  })),
+  ...(doc.value.notes.length ? [{ value: 'accessibility', label: '交互与无障碍' }] : []),
+] : [])
+watch(() => [route.hash, doc.value] as const, () => {
+  const id = route.hash.slice(1)
+  const group = apiTree.value.find(item => item.children?.some(child => child.value === id))
+  if (!group && !apiTree.value.some(item => item.value === id)) return
+  selectApi(id)
+}, { immediate: true })
+function selectApi(id: AppleValue) {
+  selectedApi.value = id
+}
+
+let scrollFrame = 0
+let contentObserver: ResizeObserver | undefined
+let indexObserver: ResizeObserver | undefined
+function syncScrollSelection() {
+  scrollFrame = 0
+  const content = documentationContent.value
+  if (!content) return
+  const targets = apiTree.value.flatMap(section => [section, ...(section.children || [])])
+    .map(item => ({ id: item.value, element: document.getElementById(String(item.value)) }))
+    .filter(target => target.element && content.contains(target.element))
+  if (!targets.length) return
+  let active = targets[0].id
+  for (const target of targets) {
+    const offset = Math.max(100, parseFloat(getComputedStyle(target.element!).scrollMarginTop) || 0)
+    if (target.element!.getBoundingClientRect().top > offset + 1) break
+    active = target.id
+  }
+  // The final section may be too short to reach the reading line above the footer.
+  if (window.scrollY > 0 && window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 2) {
+    active = targets[targets.length - 1].id
+  }
+  selectApi(active)
+}
+function queueScrollSelection() {
+  if (!scrollFrame) scrollFrame = requestAnimationFrame(syncScrollSelection)
+}
+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
+}
+watch([selectedApi, expandedSections], async () => {
+  await nextTick()
+  revealSelection()
+}, { deep: true })
+watch(doc, async () => {
+  await nextTick()
+  contentObserver?.disconnect()
+  if (documentationContent.value) contentObserver?.observe(documentationContent.value)
+  queueScrollSelection()
+}, { flush: 'post' })
+onMounted(() => {
+  window.addEventListener('scroll', queueScrollSelection, { passive: true })
+  window.addEventListener('resize', queueScrollSelection)
+  contentObserver = new ResizeObserver(queueScrollSelection)
+  if (documentationContent.value) contentObserver.observe(documentationContent.value)
+  indexObserver = new ResizeObserver(revealSelection)
+  const tree = documentationIndex.value?.querySelector<HTMLElement>('.apple-tree-size')
+  if (tree) indexObserver.observe(tree)
+  queueScrollSelection()
+})
+onBeforeUnmount(() => {
+  window.removeEventListener('scroll', queueScrollSelection)
+  window.removeEventListener('resize', queueScrollSelection)
+  contentObserver?.disconnect()
+  indexObserver?.disconnect()
+  cancelAnimationFrame(scrollFrame)
+})
+
+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}` })
+  await nextTick()
+  document.getElementById(id)?.scrollIntoView({ block: 'start' })
+}
+
+</script>
+<style scoped>
+.documentation-page { max-width: 1440px; margin: 0 auto; padding: 40px; }
+.documentation-page > :deep(.apple-link) { display: inline-flex; align-items: center; gap: 8px; font-size: 13px; }
+.documentation-heading { margin: 12px 0 36px 0; }
+.documentation-heading h1 { margin: 12px 0; font-size: clamp(32px, 4vw, 48px); letter-spacing: -.04em; }
+.documentation-heading h1 span { display: inline-block; margin-left: 18px; color: var(--apple-secondary); font-weight: 400; font-size: 24px; letter-spacing: -.02em; }
+.documentation-heading p { color: var(--apple-secondary); font-size: 15px; line-height: 1.7; }
+.documentation-content { min-width: 0; }
+.component-overview { margin-bottom: 32px;  }
+@media (max-width: 720px) { .documentation-page { padding: 40px; } .documentation-heading { margin: 24px 0; } .documentation-heading h1 span { display: block; margin: 8px 0 0; font-size: 20px; } }
+</style>