apptify 0.6.1 → 0.7.0

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

@@ -0,0 +1,89 @@
+<template>
+  <div data-testid="component-playground" :data-component="doc.name">
+    <LiveVueEditor :files="files" :baseline-files="baselineFiles" active-file="App.vue" preview-surface reset-label="恢复当前配置" @restore="reset">
+      <template #configuration>
+        <section class="configuration" role="region" :aria-label="`${doc.name} 配置`">
+          <div class="config-heading"><h3>配置 {{ doc.name }}</h3><AppleLink as="button" @click="reset">重置</AppleLink></div>
+          <div class="config-grid">
+            <div v-for="entry in doc.props" :key="entry.name" class="prop-control" :data-prop-control="entry.name">
+              <AppleCheckbox v-if="entry.default === 'undefined' && !entry.required" v-model="config.props[entry.name].enabled" :label="`使用 ${entry.name}`" />
+              <AppleSwitch v-if="controls[entry.name].kind === 'boolean'" :model-value="config.props[entry.name].value === true" @update:model-value="config.props[entry.name].value = $event" :label="entry.name" :disabled="!config.props[entry.name].enabled" />
+              <AppleSelect v-else-if="controls[entry.name].kind === 'select'" :model-value="String(config.props[entry.name].value)" @update:model-value="config.props[entry.name].value = String($event)" :items="controls[entry.name].options.map(value => ({ label: value, value }))" :label="entry.name" :disabled="!config.props[entry.name].enabled" />
+              <AppleTextarea v-else-if="['json', 'expression'].includes(controls[entry.name].kind)" :model-value="String(config.props[entry.name].value)" @update:model-value="config.props[entry.name].value = String($event)" :label="entry.name" :hint="controls[entry.name].kind === 'json' ? 'JSON' : 'JavaScript 表达式'" :rows="3" :error="errors[entry.name] || ''" :disabled="!config.props[entry.name].enabled" />
+              <AppleInput v-else :model-value="String(config.props[entry.name].value)" @update:model-value="config.props[entry.name].value = String($event)" :label="entry.name" :error="errors[entry.name] || ''" :disabled="!config.props[entry.name].enabled" />
+            </div>
+          </div>
+          <AppleAccordion v-if="doc.slots.length" :items="[{ label: '插槽', value: 'slots' }]">
+            <template #item>
+              <div class="slot-controls">
+                <div v-for="entry in doc.slots" :key="entry.name" class="slot-control">
+                  <AppleSwitch v-model="config.slots[entry.name].enabled" :label="entry.name" />
+                  <template v-if="config.slots[entry.name].enabled">
+                    <AppleInput v-if="entry.name.includes('${')" v-model="config.slots[entry.name].name" :label="`${entry.name} 名称`" />
+                    <AppleTextarea v-model="config.slots[entry.name].code" :label="`${entry.name} 模板`" :rows="4" />
+                  </template>
+                </div>
+              </div>
+            </template>
+          </AppleAccordion>
+          <AppleAlert v-if="compileError" tone="danger" title="配置有误" :message="compileError" />
+        </section>
+      </template>
+    </LiveVueEditor>
+  </div>
+</template>
+
+<script setup lang="ts">
+import { computed, defineAsyncComponent, onBeforeUnmount, reactive, ref, shallowRef, watch } from 'vue'
+import { parse, compileScript, compileTemplate } from 'vue/compiler-sfc'
+import { AppleAccordion, AppleAlert, AppleCheckbox, AppleInput, AppleLink, AppleSelect, AppleSwitch, AppleTextarea } from 'apptify'
+import type { ComponentDocument } from './contract'
+import { createPlaygroundConfig, generateComponentCode, propControl, propExpression } from './component-playground'
+
+const props = defineProps<{ doc: ComponentDocument }>()
+const LiveVueEditor = defineAsyncComponent(() => import('./LiveVueEditor.vue'))
+const config = reactive(createPlaygroundConfig(props.doc))
+const baselineFiles = { 'App.vue': generateComponentCode(props.doc, createPlaygroundConfig(props.doc)) }
+const files = shallowRef(baselineFiles)
+const errors = ref<Record<string, string>>({})
+const compileError = ref('')
+const controls = computed(() => Object.fromEntries(props.doc.props.map(entry => [entry.name, propControl(entry)])))
+let updateTimer: ReturnType<typeof setTimeout> | undefined
+
+function update() {
+  errors.value = {}
+  for (const entry of props.doc.props) {
+    if (!config.props[entry.name].enabled) continue
+    try { propExpression(entry, config.props[entry.name]) }
+    catch (error) { errors.value[entry.name] = error instanceof Error ? error.message : String(error) }
+  }
+  if (Object.keys(errors.value).length) { compileError.value = '请修正标记的属性。'; return }
+  try {
+    const code = generateComponentCode(props.doc, config)
+    const { descriptor, errors: parseErrors } = parse(code, { filename: 'App.vue' })
+    if (parseErrors.length) throw parseErrors[0]
+    const script = compileScript(descriptor, { id: 'component-playground' })
+    const template = compileTemplate({ source: descriptor.template!.content, filename: 'App.vue', id: 'component-playground', compilerOptions: { bindingMetadata: script.bindings } })
+    if (template.errors.length) throw template.errors[0]
+    compileError.value = ''
+    files.value = { 'App.vue': code }
+  } catch (error) { compileError.value = error instanceof Error ? error.message : String(error) }
+}
+watch(config, () => { clearTimeout(updateTimer); updateTimer = setTimeout(update, 150) }, { deep: true })
+function reset() {
+  clearTimeout(updateTimer)
+  Object.assign(config, createPlaygroundConfig(props.doc))
+  update()
+}
+onBeforeUnmount(() => clearTimeout(updateTimer))
+</script>
+
+<style scoped>
+.configuration, .slot-controls, .slot-control { display: grid; gap: 20px; min-width: 0; }
+.config-heading { display: flex; align-items: center; justify-content: space-between; gap: 16px; }
+.config-heading h3 { margin: 0; font-size: 16px; overflow-wrap: anywhere; }
+.config-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px; }
+.prop-control { display: grid; align-content: start; gap: 10px; min-width: 0; }
+.slot-control + .slot-control { border-top: 1px solid var(--apple-border); padding-top: 20px; }
+@media (max-width: 1100px) { .config-grid { grid-template-columns: minmax(0, 1fr); } }
+</style>

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

@@ -26,7 +26,7 @@ defineExpose({ getEditorIns: () => editor.value?.getEditorIns() })
 .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:hover: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); }

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

@@ -1,2 +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"
+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: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: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: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/component-metadata.ts

@@ -0,0 +1,72 @@
+export interface ComponentMetadata { label: string; group: string; description: string }
+
+export const componentMetadata: Record<string, ComponentMetadata> = {
+  AppleScrollBar: { label: '滚动条', group: '基础', description: '悬浮在内容之上。' },
+  AppleButton: {"label":"按钮","group":"基础","description":"清晰的操作层级。"},
+  AppleLink: {"label":"链接","group":"基础","description":"让下一步清楚可见。"},
+  AppleSearch: {"label":"搜索","group":"基础","description":"快速找到关心的内容。"},
+  AppleProvider: {"label":"主题容器","group":"基础","description":"独立区域，也有统一的设计语言。"},
+  AppleOverlayHost: {"label":"弹层宿主","group":"基础","description":"显示当前上下文的弹层与通知。"},
+  AppleContainer: {"label":"内容容器","group":"基础","description":"在不同屏幕上保留合适的内容宽度。"},
+  AppleStack: {"label":"弹性布局","group":"基础","description":"有序排列，自然换行。"},
+  AppleGrid: {"label":"网格布局","group":"基础","description":"让列数随内容空间变化。"},
+  AppleCard: {"label":"卡片","group":"基础","description":"来自 Apple Store 的产品表达。"},
+  AppleImage: {"label":"图片与预览","group":"基础","description":"让值得细看的内容更近一步。"},
+  AppleAvatar: {"label":"头像","group":"基础","description":"为每一位用户保留位置。"},
+  AppleAvatarGroup: {"label":"头像组","group":"基础","description":"一起参与的人，一眼可见。"},
+  AppleBadge: {"label":"徽标","group":"基础","description":"不打扰，也不遗漏。"},
+  AppleTag: {"label":"标签","group":"基础","description":"轻量的分类与状态。"},
+  AppleDivider: {"label":"分隔线","group":"基础","description":"恰到好处的分界。"},
+  AppleInput: {"label":"输入框","group":"表单","description":"每一次输入，都自然流畅。"},
+  AppleTextarea: {"label":"多行输入","group":"表单","description":"为更长的想法留白。"},
+  AppleSelect: {"label":"选择器","group":"表单","description":"从容找到你的选择。"},
+  AppleAutocomplete: {"label":"自动补全","group":"表单","description":"想到哪里，找到哪里。"},
+  AppleCheckbox: {"label":"复选框","group":"表单","description":"一个，或不止一个。"},
+  AppleRadioGroup: {"label":"单选框","group":"表单","description":"专注于一个明确的选择。"},
+  AppleSwitch: {"label":"开关","group":"表单","description":"简单的一开一关。"},
+  AppleSlider: {"label":"滑块","group":"表单","description":"把控制权交给指尖。"},
+  AppleStepper: {"label":"步进器","group":"表单","description":"精确一点，也轻松一点。"},
+  AppleSegmentedControl: {"label":"分段控制","group":"表单","description":"在相邻的视图间切换。"},
+  AppleDatePicker: {"label":"日期与时间","group":"表单","description":"为值得记住的日子。"},
+  AppleColorPicker: {"label":"颜色选择","group":"表单","description":"找到属于你的颜色。"},
+  AppleUpload: {"label":"文件上传","group":"表单","description":"拖入文件，继续创作。"},
+  AppleOtpInput: {"label":"验证码","group":"表单","description":"验证步骤，也可以很顺手。"},
+  AppleCascader: {"label":"级联选择","group":"表单","description":"从整体，找到细节。"},
+  AppleRate: {"label":"评分","group":"表单","description":"记录真实的感受。"},
+  AppleForm: {"label":"表单验证","group":"表单","description":"把完整提交做好。"},
+  AppleFormField: {"label":"表单字段","group":"表单","description":"为自定义控件补齐标签与验证信息。"},
+  AppleNavibar: {"label":"顶部导航栏","group":"导航","description":"随可用宽度折叠的顶部导航。"},
+  AppleAside: {"label":"侧栏容器","group":"导航","description":"图片归位后，导航自然恢复。"},
+  AppleTabs: {"label":"标签页","group":"导航","description":"内容各归其位。"},
+  AppleTabBar: {"label":"页签栏","group":"导航","description":"相邻页面，自然衔接。"},
+  AppleBreadcrumbs: {"label":"面包屑","group":"导航","description":"始终知道身在何处。"},
+  ApplePagination: {"label":"分页","group":"导航","description":"一步步，轻松浏览。"},
+  AppleSteps: {"label":"步骤条","group":"导航","description":"每一步，都有进展。"},
+  AppleAccordion: {"label":"折叠面板","group":"数据展示","description":"需要时，再展开。"},
+  AppleTable: {"label":"数据表格","group":"数据展示","description":"复杂信息，清晰呈现。"},
+  AppleTree: {"label":"树形结构","group":"数据展示","description":"有层次，也有条理。"},
+  AppleList: {"label":"列表","group":"数据展示","description":"内容优先的日常界面。"},
+  AppleTimeline: {"label":"时间线","group":"数据展示","description":"把发生的事串联起来。"},
+  AppleStatistic: {"label":"统计数值","group":"数据展示","description":"重要数据，一目了然。"},
+  AppleDialog: {"label":"对话框","group":"反馈","description":"重要的决定，值得专注。"},
+  AppleDrawer: {"label":"抽屉","group":"反馈","description":"让补充信息就近展开。"},
+  AppleSheet: {"label":"底部面板","group":"反馈","description":"为拇指设计的临时空间。"},
+  AppleSnackbar: {"label":"轻提示","group":"反馈","description":"及时回应，不必打断。"},
+  AppleAlert: {"label":"提示信息","group":"反馈","description":"让状态清楚可见。"},
+  AppleProgress: {"label":"进度条","group":"反馈","description":"等待，也能心中有数。"},
+  AppleSpinner: {"label":"加载中","group":"反馈","description":"给等待一个轻巧的回应。"},
+  AppleSkeleton: {"label":"骨架屏","group":"反馈","description":"内容到达之前。"},
+  AppleEmpty: {"label":"空状态","group":"反馈","description":"没有内容，也不空洞。"},
+  ApplePopover: {"label":"气泡面板","group":"反馈","description":"让更多操作触手可及。"},
+  AppleTooltip: {"label":"文字提示","group":"反馈","description":"在需要的时候多说一句。"},
+  AppleMenu: {"label":"下拉菜单","group":"反馈","description":"按需展开的操作列表。"},
+  AppleActionSheet: {"label":"动作面板","group":"移动交互","description":"熟悉、直接的移动操作。"},
+  ApplePullRefresh: {"label":"下拉刷新","group":"移动交互","description":"轻轻下拉，获取新内容。"},
+  AppleBackTop: {"label":"回到顶部","group":"移动交互","description":"回到开始，毫不费力。"},
+  AppleFloatingGroup: {"label":"悬浮操作组","group":"移动交互","description":"常用操作，触手可及。"},
+  AppleSpeedDial: {"label":"全局快捷操作","group":"移动交互","description":"目录与常用操作，集中在一处。"},
+  AppleSpeedDialItem: {"label":"快捷操作项","group":"移动交互","description":"页面声明，全局呈现。"},
+  AppleAutoSize: {"label":"自适应尺寸","group":"基础","description":"内容变化，布局随行。"},
+  AppleTransition: {"label":"动效容器","group":"基础","description":"为页面保留连续感。"},
+  AppleInfiniteScroll: {"label":"无限滚动","group":"移动交互","description":"浏览，不必被翻页打断。"},
+}

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

@@ -0,0 +1,162 @@
+import type { ApiEntry, ComponentDocument } from './contract'
+import { playgroundExample, slotExample } from './playground-examples'
+
+export type ControlKind = 'boolean' | 'text' | 'number' | 'select' | 'json' | 'expression'
+export interface PropControl { name: string; kind: ControlKind; options: string[]; required: boolean }
+export interface PropValue { enabled: boolean; value: string | boolean }
+export interface SlotValue { enabled: boolean; name: string; scope?: string; code: string }
+export interface PlaygroundConfig { props: Record<string, PropValue>; slots: Record<string, SlotValue> }
+
+export function propControl(entry: ApiEntry): PropControl {
+  const options = [...entry.type.matchAll(/'([^']+)'/g)].map(match => match[1])
+  const enumType = options.length > 0 && /^('[^']+'\s*(\|\s*('[^']+'|undefined)\s*)*)$/.test(entry.type)
+  const kind: ControlKind = entry.type === 'boolean' ? 'boolean'
+    : enumType ? 'select' : entry.type === 'string' ? 'text' : entry.type === 'number' ? 'number'
+    : /=>|Component|File\[\]/.test(entry.type) ? 'expression'
+    : /\[\]|Record</.test(entry.type) && !entry.type.includes('undefined') ? 'json' : 'expression'
+  return { name: entry.name, kind, options, required: !!entry.required }
+}
+
+function editableValue(control: PropControl, expression: string): string | boolean {
+  if (control.kind === 'boolean') return expression === 'true'
+  if (control.kind === 'text' || control.kind === 'select') {
+    if (expression === 'undefined') return ''
+    try { return String(JSON.parse(expression)) } catch { return expression.replace(/^'|'$/g, '') }
+  }
+  if (control.kind === 'json') {
+    try { return JSON.stringify(JSON.parse(expression), null, 2) } catch { return expression === 'undefined' ? '[]' : expression }
+  }
+  return expression === 'undefined' ? '' : expression
+}
+
+export function createPlaygroundConfig(doc: ComponentDocument): PlaygroundConfig {
+  const example = playgroundExample(doc.name)
+  return {
+    props: Object.fromEntries(doc.props.map(entry => {
+      const expression = example.props?.[entry.name] ?? entry.default ?? 'undefined'
+      return [entry.name, { enabled: expression !== 'undefined' || !!entry.required, value: editableValue(propControl(entry), expression) }]
+    })),
+    slots: Object.fromEntries(doc.slots.map(entry => {
+      const example = slotExample(doc.name, entry.name)
+      const name = entry.name.replace('${value}', 'first').replace('${key}', 'name')
+      return [entry.name, { ...example, enabled: !!example.enabled, name }]
+    })),
+  }
+}
+
+const scriptLiteral = (value: unknown) => JSON.stringify(value).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029')
+const attr = (value: string) => value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+const kebab = (value: string) => value.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase()
+
+export function propExpression(entry: ApiEntry, input: PropValue): string {
+  const control = propControl(entry)
+  if (control.kind === 'boolean') return String(input.value === true)
+  if (control.kind === 'text' || control.kind === 'select') return scriptLiteral(String(input.value))
+  if (control.kind === 'json') return scriptLiteral(JSON.parse(String(input.value)))
+  const expression = String(input.value).trim()
+  if (control.kind === 'number' && !/^-?(?:Infinity|(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)$/i.test(expression)) throw new Error(`${entry.name}：请输入数字或 Infinity。`)
+  if (!expression) throw new Error(`${entry.name}：请输入 JavaScript 表达式，或关闭该属性。`)
+  return expression.replace(/<\/script/gi, '<\\/script')
+}
+
+export function generateComponentCode(doc: ComponentDocument, config: PlaygroundConfig): string {
+  const example = playgroundExample(doc.name)
+  const enabledProps = doc.props.filter(entry => config.props[entry.name].enabled)
+  const expressions = enabledProps.map(entry => `        ${scriptLiteral(entry.name)}: (${propExpression(entry, config.props[entry.name])})`).join(',\n')
+  const bindings = enabledProps.map(entry => `        :${kebab(entry.name)}="props.${entry.name}"`)
+  const listeners = doc.events.map(entry => {
+    let handler = `(...args) => record('${entry.name}', ...args)`
+    if (entry.name.startsWith('update:')) handler = `(value) => { props.${entry.name.slice(7)} = value; record('${entry.name}', value) }`
+    if (['refresh', 'load', 'retry'].includes(entry.name)) handler = `(done) => finishBatch('${entry.name}', done)`
+    if (doc.name === 'AppleForm' && entry.name === 'reset') handler = `() => { fieldValue = ''; record('reset') }`
+    return `        @${kebab(entry.name)}="${attr(handler)}"`
+  })
+  const slots = Object.values(config.slots).filter(slot => slot.enabled).map(slot => {
+    if (!/^[\w-]+$/.test(slot.name)) throw new Error('插槽名称只能包含字母、数字、下划线和连字符。')
+    return `        <template #${slot.name}${slot.scope ? `="${attr(slot.scope)}"` : ''}>${slot.code}</template>`
+  }).join('\n')
+  const component = `      <${doc.name}\n        ref="demo"\n${[...bindings, ...listeners].join('\n')}\n      >\n${slots}\n      </${doc.name}>`
+  const names = [...new Set([doc.name, 'AppleButton', 'AppleInput', 'AppleLink', 'AppleTextarea'])]
+  const methods = doc.methods.map(method => ({ label: method.name, expression: `$refs.demo.${method.name.split('(')[0]}()` }))
+  const modal = ['AppleDialog', 'AppleDrawer', 'AppleSheet', 'AppleActionSheet', 'AppleSnackbar', 'AppleAlert'].includes(doc.name)
+  const actions = [...(modal ? [{ label: '打开 / 重新显示', expression: 'props.modelValue = true' }] : []), ...methods, ...(example.actions || [])]
+  const actionButtons = actions.length ? `      <div class="actions">${actions.map(action => `<AppleLink as="button" @click="${attr(action.expression)}">${attr(action.label)}</AppleLink>`).join('')}</div>` : ''
+  const modelProps = doc.props.filter(prop => doc.events.some(event => event.name === `update:${prop.name}`))
+  const modelReadout = modelProps.map(prop => `<output>${prop.name} = {{ display(props.${prop.name}) }}</output>`).join('\n      ')
+  return `<script>
+import { ${names.join(', ')} } from 'apptify'
+import { markRaw } from 'vue'
+import { Mail, Star, Check, Search, ArrowRight } from 'lucide-vue-next'
+
+;[Mail, Star, Check, Search, ArrowRight].forEach(markRaw)
+
+export default {
+  components: { ${names.join(', ')}, Mail, Star, Check, Search, ArrowRight },
+  data() {
+    return {
+      props: {
+${expressions}
+      },
+      fieldValue: 'Apptify', expanded: false, batches: 0, events: [], eventId: 0,
+    }
+  },
+  computed: {
+    eventLog() { return this.events.join('\\n') },
+  },
+  methods: {
+    display(value) {
+      if (value === undefined) return 'undefined'
+      const seen = new WeakSet()
+      return JSON.stringify(value, (_, current) => {
+        if (typeof current === 'function') return '[function]'
+        if (current instanceof FormData) return Object.fromEntries(current.entries())
+        if (current instanceof File) return { name: current.name, size: current.size, type: current.type }
+        if (current instanceof Event) return { type: current.type }
+        if (current && typeof current === 'object') { if (seen.has(current)) return '[circular]'; seen.add(current) }
+        return current
+      })
+    },
+    record(name, ...args) {
+      this.events.push(++this.eventId + '. ' + name + ' ' + (args.length ? args.map(this.display).join(' · ') : '无参数'))
+      if (this.events.length > 12) this.events.shift()
+    },
+    finishBatch(name, done) {
+      this.record(name, done)
+      this.batches++
+      if (name !== 'refresh' && this.batches >= 3) this.props.finished = true
+      if (name === 'retry') this.props.error = false
+      if (typeof done === 'function') done()
+    },
+  },
+}
+<\/script>
+
+<template>
+  <div class="example">
+    <section class="component-section" aria-label="${doc.name} 示例">
+      ${example.before || ''}
+${actionButtons}
+${component}
+      ${modelReadout}
+    </section>
+    <section v-if="${doc.events.length > 0}" class="events-section" aria-label="事件记录">
+      <div class="event-heading"><h3>事件记录</h3><AppleLink as="button" @click="events = []">清除记录</AppleLink></div>
+      <AppleTextarea :model-value="eventLog" readonly :rows="6" :resize="false" aria-label="事件记录内容" placeholder="等待操作…" />
+    </section>
+  </div>
+</template>
+
+<style scoped>
+.example { display: grid; gap: 28px; padding: 28px 24px; min-width: 0; }
+.component-section { display: grid; gap: 20px; min-width: 0; }
+.actions { display: flex; flex-wrap: wrap; gap: 20px; }
+.events-section { border-top: 1px solid var(--apple-border); padding-top: 20px; min-width: 0; }
+.event-heading { display: flex; align-items: center; justify-content: space-between; margin-bottom: 12px; }
+h3 { margin: 0; font-size: 14px; }
+output { color: var(--apple-secondary); font: 12px/1.6 ui-monospace, monospace; overflow-wrap: anywhere; }
+.tile { padding: 20px; border-radius: 8px; background: var(--apple-surface-alt); min-width: 0; }
+.scroll-demo { height: 220px; overflow: auto; padding: 16px; border: 1px solid var(--apple-border); border-radius: 8px; }
+.example :deep(.apple-provider) { padding: 20px; display: grid; gap: 16px; border-radius: 8px; }
+@media (max-width: 480px) { .example { padding: 24px 16px; } }
+</style>`
+}

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

@@ -1,7 +1,7 @@
 /** 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 ApiEntry extends ApiDefinition { id: string; required?: boolean; example?: VueExample }
 export interface ComponentDocument {
   name: string
   source: string

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

@@ -1,5 +1,6 @@
 import { defineAsyncComponent, type Component } from 'vue'
 import type { ComponentDocument } from './contract'
+import { componentMetadata } from './component-metadata'
 /** Lightweight route directory. Each document is downloaded only on its own page. */
 export interface DocumentRegistration {
   name: string
@@ -9,12 +10,20 @@ export interface DocumentRegistration {
   preview?: Component
   load: () => Promise<{ default: ComponentDocument }>
 }
-export const componentDocuments: Record<string, DocumentRegistration> = {
+const handbooks = import.meta.glob<{ default: ComponentDocument }>('./handbooks/apple-*.ts')
+export const componentDocuments: Record<string, DocumentRegistration> = Object.fromEntries(Object.entries(componentMetadata).map(([name, item]) => {
+  const slug = name.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+  return [slug, {
+    name, ...item,
+    load: handbooks[`./handbooks/${slug}.ts`],
+  }]
+}))
+Object.assign(componentDocuments, {
   'apple-input': {
     name: 'AppleInput', label: '输入框', group: '表单',
     description: '从输入、反馈到辅助操作，逐条了解输入框的行为与接口。',
     preview: defineAsyncComponent(() => import('./AppleInputPreview.vue')),
     load: () => import('./apple-input'),
   },
-}
+} satisfies Record<string, DocumentRegistration>)
 export const componentDocumentPath = (slug: string) => `/component-docs/${slug}`

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

@@ -0,0 +1,22 @@
+import type { ApiDefinition, ComponentDocument } from './contract'
+
+type Definition = Omit<ComponentDocument, 'props' | 'events' | 'slots' | 'methods'> & {
+  props: (ApiDefinition & { required?: boolean })[]
+  events: ApiDefinition[]
+  slots: ApiDefinition[]
+  methods: ApiDefinition[]
+}
+
+export function defineHandbook(definition: Definition): ComponentDocument {
+  const entries = (group: string, list: ApiDefinition[]) => list.map(entry => ({
+    ...entry,
+    id: `${group}-${entry.name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/[^\w-]+/g, '-').replace(/-+$/, '').toLowerCase()}`,
+  }))
+  return {
+    ...definition,
+    props: entries('prop', definition.props),
+    events: entries('event', definition.events),
+    slots: entries('slot', definition.slots),
+    methods: entries('method', definition.methods),
+  }
+}

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

@@ -0,0 +1,66 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleAccordion",
+  "source": "src/components/content.ts",
+  "props": [
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "items",
+      "type": "AppleItem[]",
+      "default": "[]",
+      "description": "按顺序显示的选项。每项 value 唯一，保留字符串和数字的类型区别。结构：{ label: string; value: string | number; disabled?: boolean; description?: string; href?: string; content?: string }。"
+    },
+    {
+      "name": "modelValue",
+      "type": "string | number | (string | number)[] | undefined",
+      "default": "undefined",
+      "description": "展开项 value；multiple=true 时使用 value 数组。单选收起最后一项时发出 undefined。省略模型时内部管理。"
+    },
+    {
+      "name": "multiple",
+      "type": "boolean",
+      "default": "false",
+      "description": "允许同时展开多项；开启时更新事件返回数组。"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "default": "false",
+      "description": "禁用控件的交互。选项自身的 disabled 仍然独立生效。"
+    }
+  ],
+  "events": [
+    {
+      "name": "update:modelValue",
+      "type": "(value: string | number | (string | number)[] | undefined) => void",
+      "description": "交互更新时发出新模型值；可使用 v-model 接收。"
+    },
+    {
+      "name": "change",
+      "type": "(value: string | number | (string | number)[] | undefined) => void",
+      "description": "用户提交选择或调整时发出当前值；直接从父组件赋值不会主动发出此事件。"
+    }
+  ],
+  "slots": [
+    {
+      "name": "item",
+      "type": "({ item: AppleItem, open: boolean }) => VNode[]",
+      "description": "通用折叠项正文，替代 item.content。"
+    },
+    {
+      "name": "item-${value}",
+      "type": "({ item: AppleItem, open: boolean }) => VNode[]",
+      "description": "具体项的正文，优先于通用 item 插槽。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "使用真实内容与可访问名称；交互控件可通过 Tab 和原生键盘方式操作，动效遵循外层偏好。"
+  ]
+})

package/templates/playground/src/editor/handbooks/apple-action-sheet.ts

@@ -0,0 +1,72 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleActionSheet",
+  "source": "src/components/overlays.ts",
+  "props": [
+    {
+      "name": "modelValue",
+      "type": "boolean",
+      "default": "false",
+      "description": "是否打开动作面板，默认 false。"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "default": "\"\"",
+      "description": "标题文字。"
+    },
+    {
+      "name": "message",
+      "type": "string",
+      "default": "\"\"",
+      "description": "动作列表上方的说明文字，与 default 插槽内容同时显示。"
+    },
+    {
+      "name": "items",
+      "type": "AppleMenuItem[]",
+      "default": "[]",
+      "description": "动作数组：{ label, value: string|number, disabled?, danger?, description?, icon?: Component }。default 插槽替代整个动作列表。"
+    },
+    {
+      "name": "cancelText",
+      "type": "string",
+      "default": "\"取消\"",
+      "description": "取消按钮文字，空字符串隐藏按钮；取消返回 undefined 和 cancel 原因。"
+    },
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    }
+  ],
+  "events": [
+    {
+      "name": "update:modelValue",
+      "type": "(value: boolean) => void",
+      "description": "交互更新时发出新模型值；可使用 v-model 接收。"
+    },
+    {
+      "name": "select",
+      "type": "(value: string | number, item: AppleMenuItem) => void",
+      "description": "选中可用动作时发出 value 与完整项，随后更新打开状态并发出 close。"
+    },
+    {
+      "name": "close",
+      "type": "(value: unknown, reason: 'select' | 'close' | 'cancel' | 'escape' | 'backdrop') => void",
+      "description": "选中动作时 value 为动作值；取消和背景/Escape 关闭时通常为 undefined。自定义 close(value) 保留传入值。"
+    }
+  ],
+  "slots": [
+    {
+      "name": "default",
+      "type": "({ select: (item: AppleMenuItem) => void, close: (value?: unknown) => void }) => VNode[]",
+      "description": "替代默认动作列表；调用 select(item) 保留选择事件与关闭行为，取消按钮仍保留。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "自定义 default 插槽覆盖动作列表，使用 select(item) 保留结果回传；取消按钮仍保留。"
+  ]
+})