apptify 0.6.1 → 0.7.0

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

@@ -0,0 +1,38 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleDivider",
+  "source": "src/components/content.ts",
+  "props": [
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "default": "undefined",
+      "description": "分隔文字和可访问名称；default 插槽可替代可见文字。"
+    },
+    {
+      "name": "vertical",
+      "type": "boolean",
+      "default": "false",
+      "description": "使用竖向分隔线，设置 aria-orientation=vertical；布局高度由外层决定。"
+    }
+  ],
+  "events": [],
+  "slots": [
+    {
+      "name": "default",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "替代可见分隔文字。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "使用真实内容与可访问名称；交互控件可通过 Tab 和原生键盘方式操作，动效遵循外层偏好。"
+  ]
+})

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

@@ -0,0 +1,151 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleDrawer",
+  "source": "src/components/overlays.ts",
+  "props": [
+    {
+      "name": "modelValue",
+      "type": "boolean",
+      "default": "false",
+      "description": "是否打开。使用 v-model 接收关闭操作的 false。"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "default": "\"\"",
+      "description": "标题文字。"
+    },
+    {
+      "name": "message",
+      "type": "string",
+      "default": "\"\"",
+      "description": "正文文字；提供 default 插槽时以插槽内容为准。"
+    },
+    {
+      "name": "ariaLabel",
+      "type": "string",
+      "default": "\"对话框\"",
+      "description": "没有 title 时用于对话框的可访问名称。"
+    },
+    {
+      "name": "persistent",
+      "type": "boolean",
+      "default": "false",
+      "description": "阻止 Escape 和背景点击关闭；显式关闭、确认和取消仍可使用。"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "default": "false",
+      "description": "阻止所有交互关闭、确认和取消，显示忙碌状态。"
+    },
+    {
+      "name": "closeOnConfirm",
+      "type": "boolean",
+      "default": "true",
+      "description": "确认后自动关闭。异步保存时可设 false，由应用控制 loading 和 modelValue。"
+    },
+    {
+      "name": "confirmText",
+      "type": "string",
+      "default": "\"确定\"",
+      "description": "确认按钮文字，空字符串隐藏按钮。"
+    },
+    {
+      "name": "cancelText",
+      "type": "string",
+      "default": "\"取消\"",
+      "description": "取消按钮文字，空字符串隐藏按钮。"
+    },
+    {
+      "name": "showFooter",
+      "type": "boolean",
+      "default": "false",
+      "description": "显示默认操作区；自定义 footer 插槽始终可以显示。Dialog 默认 true，Drawer/Sheet 默认 false。"
+    },
+    {
+      "name": "closable",
+      "type": "boolean",
+      "default": "true",
+      "description": "显示关闭按钮。"
+    },
+    {
+      "name": "width",
+      "type": "string | number",
+      "default": "440",
+      "description": "宽度。数字按 px，字符串作为 CSS 尺寸；仍受可用空间约束。"
+    },
+    {
+      "name": "placement",
+      "type": "'left' | 'right' | 'bottom'",
+      "default": "\"right\"",
+      "description": "抽屉方向为 left、right、bottom；Sheet 默认 bottom。Dialog 不使用方向来改变其居中布局。"
+    },
+    {
+      "name": "tone",
+      "type": "string",
+      "default": "\"default\"",
+      "description": "语义色；danger 使用危险确认按钮。"
+    },
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    }
+  ],
+  "events": [
+    {
+      "name": "update:modelValue",
+      "type": "(value: boolean) => void",
+      "description": "交互更新时发出新模型值；可使用 v-model 接收。"
+    },
+    {
+      "name": "close",
+      "type": "(value: unknown, reason: 'escape' | 'backdrop' | 'cancel' | 'confirm' | 'close') => void",
+      "description": "交互关闭时发出结果和原因；确认 true，取消 false，直接关闭通常 undefined。外部直接设置 modelValue=false 不会主动发出 close。"
+    },
+    {
+      "name": "confirm",
+      "type": "(value: true) => void",
+      "description": "点击确认时触发；closeOnConfirm=true 时随后关闭。"
+    },
+    {
+      "name": "cancel",
+      "type": "(value: false) => void",
+      "description": "点击取消时触发，随后关闭。"
+    },
+    {
+      "name": "open",
+      "type": "() => void",
+      "description": "面板挂载并注册焦点与层级管理后触发。"
+    },
+    {
+      "name": "after-close",
+      "type": "() => void",
+      "description": "退出动效完成并释放层级状态后触发。"
+    }
+  ],
+  "slots": [
+    {
+      "name": "title",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "替代标题内容；仍应通过 title 或 ariaLabel 提供对话框名称。"
+    },
+    {
+      "name": "default",
+      "type": "({ close: (value?: unknown) => void }) => VNode[]",
+      "description": "对话框正文，替代 message；调用 close(value) 交回结果。"
+    },
+    {
+      "name": "footer",
+      "type": "({ close: (value?: unknown) => void, confirm: () => void, cancel: () => void }) => VNode[]",
+      "description": "替代默认按钮区；即使 showFooter=false 也会显示。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "使用真实内容与可访问名称；交互控件可通过 Tab 和原生键盘方式操作，动效遵循外层偏好。"
+  ]
+})

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

@@ -0,0 +1,43 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleEmpty",
+  "source": "src/components/content.ts",
+  "props": [
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "title",
+      "type": "string",
+      "default": "\"这里还没有内容\"",
+      "description": "标题文字。"
+    },
+    {
+      "name": "description",
+      "type": "string",
+      "default": "\"\"",
+      "description": "补充说明文字。"
+    }
+  ],
+  "events": [],
+  "slots": [
+    {
+      "name": "icon",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "替代默认空状态图标。"
+    },
+    {
+      "name": "default",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "标题与说明后的附加内容或操作。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "使用真实内容与可访问名称；交互控件可通过 Tab 和原生键盘方式操作，动效遵循外层偏好。"
+  ]
+})

package/templates/playground/src/editor/handbooks/apple-floating-group.ts

@@ -0,0 +1,51 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleFloatingGroup",
+  "source": "src/components/content.ts",
+  "props": [
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "backTop",
+      "type": "boolean",
+      "default": "true",
+      "description": "在组内最后放置回到顶部按钮。"
+    },
+    {
+      "name": "target",
+      "type": "string",
+      "default": "\"\"",
+      "description": "滚动容器的 CSS 选择器。空字符串使用 window；目标应在组件挂载时已存在。"
+    },
+    {
+      "name": "threshold",
+      "type": "number",
+      "default": "300",
+      "description": "传给内置 BackTop 的滚动显示阈值，单位 px。"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "default": "\"快捷操作\"",
+      "description": "控件名称或区域的可访问名称。无可见名称时应提供 aria-label。"
+    }
+  ],
+  "events": [],
+  "slots": [
+    {
+      "name": "default",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "附加操作，排列在内置回顶按钮前。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "默认固定右下并考虑安全区，回顶按钮排在附加操作之后。示例滚动容器用于体验 threshold。",
+    "与 Navibar 同为 z-index 70；图片预览时隐藏，退出开始时执行 FadeInLeft，遵循全局和局部动效设置。组内回顶按钮使用不透明背景。"
+  ]
+})

package/templates/playground/src/editor/handbooks/apple-form-field.ts

@@ -0,0 +1,69 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleFormField",
+  "source": "src/components/forms.ts",
+  "props": [
+    {
+      "name": "label",
+      "type": "string",
+      "default": "\"\"",
+      "description": "控件名称或区域的可访问名称。无可见名称时应提供 aria-label。"
+    },
+    {
+      "name": "hint",
+      "type": "string",
+      "default": "\"\"",
+      "description": "字段帮助文字；error 非空时优先显示错误，帮助文字暂时隐藏。"
+    },
+    {
+      "name": "error",
+      "type": "string",
+      "default": "\"\"",
+      "description": "显示字段错误和错误样式，不会自行执行校验或阻止表单提交。"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "default": "false",
+      "description": "通过插槽向内部输入传递 disabled；容器不会自动禁用任意插槽内容。"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "default": "false",
+      "description": "将 default 插槽的 disabled 设为 true；字段容器本身不代替内部控件执行禁用。"
+    },
+    {
+      "name": "required",
+      "type": "boolean",
+      "default": "false",
+      "description": "显示必填星号，并通过插槽传递 required；需绑定到实际输入。"
+    },
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "for",
+      "type": "string",
+      "default": "undefined",
+      "description": "自定义输入的 id，省略时自动生成。需将 default 插槽属性绑定到实际输入以关联标签与说明。"
+    }
+  ],
+  "events": [],
+  "slots": [
+    {
+      "name": "default",
+      "type": "({ id: string, disabled: boolean, required: boolean, 'aria-label'?: string, 'aria-labelledby'?: string, 'aria-invalid': boolean, 'aria-describedby'?: string }) => VNode[]",
+      "description": "将 slot props 用 v-bind 绑定到实际输入，才能传递禁用、必填和标签/提示关联。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "容器只提供字段关联属性，不会自动改写插槽内容；务必将插槽参数绑定到自定义输入。",
+    "字段名称、帮助和错误文字只用于说明。直接操作控件；原生 name、autocomplete 等属性需按实际输入类型使用。"
+  ]
+})

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

@@ -0,0 +1,76 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleForm",
+  "source": "src/components/forms.ts",
+  "props": [
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "default": "false",
+      "description": "禁用 fieldset 内的字段并阻止提交。"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "default": "false",
+      "description": "与内部异步校验状态合并，禁用 fieldset 内所有字段并阻止再次提交。"
+    },
+    {
+      "name": "validator",
+      "type": "(data: FormData) => boolean | string | Promise<boolean | string>",
+      "default": "undefined",
+      "description": "函数 (data: FormData) => boolean | string | Promise<boolean | string>。原生校验通过后执行，仅 true 表示成功；字符串作为错误，false 使用默认错误。"
+    },
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    }
+  ],
+  "events": [
+    {
+      "name": "submit",
+      "type": "(data: FormData) => void",
+      "description": "原生约束和自定义校验通过后发出表单数据；不会自动发送网络请求。"
+    },
+    {
+      "name": "invalid",
+      "type": "(error: { type: 'native' | 'custom'; message?: string }) => void",
+      "description": "原生校验失败时 type=native；自定义返回失败或抛错时 type=custom 并带 message。"
+    },
+    {
+      "name": "reset",
+      "type": "() => void",
+      "description": "原生表单重置时触发。需要在应用内同步重置 Vue model。"
+    }
+  ],
+  "slots": [
+    {
+      "name": "default",
+      "type": "({ loading: boolean }) => VNode[]",
+      "description": "表单字段与操作，loading 合并外部 loading 和内部校验状态。"
+    }
+  ],
+  "methods": [
+    {
+      "name": "validate()",
+      "type": "() => Promise<boolean>",
+      "description": "执行原生及自定义校验，返回是否通过；不会发出 submit。"
+    },
+    {
+      "name": "submit()",
+      "type": "() => Promise<void>",
+      "description": "在可用状态下执行校验，通过后发出 submit(FormData)。"
+    },
+    {
+      "name": "reset()",
+      "type": "() => void",
+      "description": "调用原生 form.reset() 并触发 reset；父组件应同步重置 Vue model。"
+    }
+  ],
+  "notes": [
+    "FormData 只包含有 name 的可提交字段。reset 重置浏览器字段，不会替应用重置所有 Vue model。"
+  ]
+})

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

@@ -0,0 +1,32 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleGrid",
+  "source": "src/components/foundation.ts",
+  "props": [
+    {
+      "name": "min",
+      "type": "number",
+      "default": "240",
+      "description": "每列最小设计宽度，单位 px；空间不足时收缩到容器宽度，列数自动适应。"
+    },
+    {
+      "name": "gap",
+      "type": "number",
+      "default": "20",
+      "description": "网格间距，单位 px。"
+    }
+  ],
+  "events": [],
+  "slots": [
+    {
+      "name": "default",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "参与自适应网格排列的子项。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "使用真实内容与可访问名称；交互控件可通过 Tab 和原生键盘方式操作，动效遵循外层偏好。"
+  ]
+})

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

@@ -0,0 +1,122 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleImage",
+  "source": "src/components/foundation.ts",
+  "props": [
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "preview",
+      "type": "boolean",
+      "default": "true",
+      "description": "点击有效图片进入内置放大预览；关闭后仍能使用图片组和轮播。"
+    },
+    {
+      "name": "gallery",
+      "type": "AppleImageItem | (string | AppleImageItem)[]",
+      "default": "[]",
+      "description": "单个图片对象或字符串/对象数组。对象：{ src?, alt?, title?, width?, height?, label?, value?, description? }。普通图片忽略无 src 的空项；carousel 可用无 src 的自定义内容。顶层没有 src/alt props。"
+    },
+    {
+      "name": "carousel",
+      "type": "boolean",
+      "default": "false",
+      "description": "轮播模式，强制 compact 布局，并启用 item 插槽和标题说明。"
+    },
+    {
+      "name": "autoplay",
+      "type": "boolean",
+      "default": "true",
+      "description": "carousel 模式自动循环播放；悬浮、聚焦、预览、拖动、页面隐藏或禁用时暂停。"
+    },
+    {
+      "name": "interval",
+      "type": "number",
+      "default": "5000",
+      "description": "carousel 自动播放间隔，单位毫秒，默认每 5 秒切换一张图片。"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "default": "false",
+      "description": "禁用打开预览、翻页、拖动及图片组键盘操作。"
+    },
+    {
+      "name": "label",
+      "type": "string",
+      "default": "\"图片轮播\"",
+      "description": "控件名称或区域的可访问名称。无可见名称时应提供 aria-label。"
+    },
+    {
+      "name": "galleryLayout",
+      "type": "'compact' | 'tiled' | 'tiled-wrap'",
+      "default": "\"compact\"",
+      "description": "compact 为分页图片条，tiled 为横向平铺，tiled-wrap 为换行平铺。"
+    },
+    {
+      "name": "galleryShape",
+      "type": "'natural' | 'square'",
+      "default": "\"natural\"",
+      "description": "natural 保留各图片比例，square 强制正方形并居中裁剪。"
+    },
+    {
+      "name": "index",
+      "type": "number",
+      "default": "0",
+      "description": "当前图片索引，从 0 开始，可用 v-model:index。非有限值归零，越界值截取到有效范围。"
+    },
+    {
+      "name": "squared",
+      "type": "boolean",
+      "default": "false",
+      "description": "强制 1:1，覆盖 aspectRatio、galleryShape 和 fit；也作用于图片组。"
+    },
+    {
+      "name": "aspectRatio",
+      "type": "string | number",
+      "default": "\"4/3\"",
+      "description": "单图或 compact 视口的 CSS aspect-ratio 值，例如 4/3、1；不是图片像素尺寸。"
+    },
+    {
+      "name": "fit",
+      "type": "'contain' | 'cover'",
+      "default": "\"cover\"",
+      "description": "contain 完整显示，cover 填满裁剪；正方形模式始终使用 cover。"
+    }
+  ],
+  "events": [
+    {
+      "name": "update:index",
+      "type": "(value: number) => void",
+      "description": "交互更新 index 时发出新值；可使用对应的命名 v-model 接收。"
+    },
+    {
+      "name": "change",
+      "type": "(value: number) => void",
+      "description": "图片组或预览索引改变时发出从 0 开始的索引。"
+    }
+  ],
+  "slots": [
+    {
+      "name": "item",
+      "type": "({ item: AppleImageItem, index: number, active: boolean }) => VNode[]",
+      "description": "仅 carousel=true 时替代整个轮播项；提供无图片内容时不会打开图片预览。"
+    },
+    {
+      "name": "caption",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "figure 的 figcaption 说明文字。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "图片数组不接受顶层 src/alt；描述应放在 gallery 对象内。预览由组件内部管理，没有独立公开 Viewer 组件。",
+    "图片组支持方向键、Home/End、拖动和分页；无效或加载失败的图片不会打开预览。横屏缩略图左右按钮在悬浮时淡入、移开时淡出，遵循 --apple-fast 和 --apple-ease；竖屏隐藏左右箭头、关闭及缩放按钮。",
+    "所有设备使用统一预览交互，平滑滚轮、缩放、旋转、翻页和进退场支持动画打断与叠加；底部胶囊依次为左旋转、缩小、可选名称、放大、右旋转，每次旋转 90°。"
+  ]
+})

package/templates/playground/src/editor/handbooks/apple-infinite-scroll.ts

@@ -0,0 +1,73 @@
+import { defineHandbook } from '../handbook'
+
+export default defineHandbook({
+  "name": "AppleInfiniteScroll",
+  "source": "src/components/content.ts",
+  "props": [
+    {
+      "name": "motion",
+      "type": "'inherit' | 'auto' | 'full' | 'reduced' | 'none'",
+      "default": "\"inherit\"",
+      "description": "局部动效偏好。inherit 跟随外层；全局与系统的减少动效设置仍是上限。"
+    },
+    {
+      "name": "loading",
+      "type": "boolean",
+      "default": "false",
+      "description": "外部加载状态；从 true 变为 false 时释放等待并重新观察。"
+    },
+    {
+      "name": "error",
+      "type": "boolean | string",
+      "default": "false",
+      "description": "true 显示默认错误，字符串显示指定错误；错误时不自动加载，提供重试按钮。"
+    },
+    {
+      "name": "finished",
+      "type": "boolean",
+      "default": "false",
+      "description": "已加载完毕；为 true 时停止自动加载并显示 finishedText。"
+    },
+    {
+      "name": "disabled",
+      "type": "boolean",
+      "default": "false",
+      "description": "禁用控件的交互。选项自身的 disabled 仍然独立生效。"
+    },
+    {
+      "name": "distance",
+      "type": "number",
+      "default": "120",
+      "description": "IntersectionObserver 的 rootMargin 预加载距离，单位 px，创建时使用，负数按 0。"
+    },
+    {
+      "name": "finishedText",
+      "type": "string",
+      "default": "\"已经到底了\"",
+      "description": "finished 为 true 时的文字。"
+    }
+  ],
+  "events": [
+    {
+      "name": "load",
+      "type": "(done: () => void) => void",
+      "description": "观察到加载区或点击“加载更多”时触发；完成后调用 done()，或让 loading 从 true 变为 false。"
+    },
+    {
+      "name": "retry",
+      "type": "(done: () => void) => void",
+      "description": "点击重试时触发；完成后释放等待，错误和 finished 状态由应用更新。"
+    }
+  ],
+  "slots": [
+    {
+      "name": "default",
+      "type": "() => VNode[]（无 slot props）",
+      "description": "已加载的列表内容。"
+    }
+  ],
+  "methods": [],
+  "notes": [
+    "完成后释放等待；示例自动执行 done() 并在第三批结束，以避免观察器无限加载。distance 在观察器创建时读取。"
+  ]
+})