apptify 0.5.1 → 0.6.0

package/dist/components/overlays.d.ts

@@ -71,6 +71,7 @@ export declare const AppleDialog: import("vue").DefineComponent<import("vue").Ex
     disposeLayer: (() => void) | null;
     isTop: boolean;
     depth: number;
+    present: boolean;
 }, {
     resolvedMotion(): string;
 }, {
@@ -217,6 +218,7 @@ export declare const AppleDrawer: import("vue").DefineComponent<import("vue").Ex
     disposeLayer: (() => void) | null;
     isTop: boolean;
     depth: number;
+    present: boolean;
 }, {
     resolvedMotion(): string;
 }, {
@@ -363,6 +365,7 @@ export declare const AppleSheet: import("vue").DefineComponent<import("vue").Ext
     disposeLayer: (() => void) | null;
     isTop: boolean;
     depth: number;
+    present: boolean;
 }, {
     resolvedMotion(): string;
 }, {
@@ -598,13 +601,13 @@ export declare const ApplePopover: import("vue").DefineComponent<import("vue").E
     internalOpen: boolean;
     depth: number;
     isTop: boolean;
+    present: boolean;
     disposeLayer: (() => void) | null;
     disposePosition: (() => void) | null;
     hoverTimer: ReturnType<typeof setTimeout> | null;
     positioned: boolean;
     positioner: PopupPositioner | null;
     positionPanel: HTMLElement | null;
-    interruptedPopup: number | undefined;
 }, {
     opened(): boolean;
 }, {
@@ -983,6 +986,7 @@ export declare const overlayComponents: {
         disposeLayer: (() => void) | null;
         isTop: boolean;
         depth: number;
+        present: boolean;
     }, {
         resolvedMotion(): string;
     }, {
@@ -1129,6 +1133,7 @@ export declare const overlayComponents: {
         disposeLayer: (() => void) | null;
         isTop: boolean;
         depth: number;
+        present: boolean;
     }, {
         resolvedMotion(): string;
     }, {
@@ -1275,6 +1280,7 @@ export declare const overlayComponents: {
         disposeLayer: (() => void) | null;
         isTop: boolean;
         depth: number;
+        present: boolean;
     }, {
         resolvedMotion(): string;
     }, {
@@ -1510,13 +1516,13 @@ export declare const overlayComponents: {
         internalOpen: boolean;
         depth: number;
         isTop: boolean;
+        present: boolean;
         disposeLayer: (() => void) | null;
         disposePosition: (() => void) | null;
         hoverTimer: ReturnType<typeof setTimeout> | null;
         positioned: boolean;
         positioner: PopupPositioner | null;
         positionPanel: HTMLElement | null;
-        interruptedPopup: number | undefined;
     }, {
         opened(): boolean;
     }, {

package/dist/core/context.d.ts

@@ -316,6 +316,7 @@ export interface AppleOptions {
     theme?: string;
     themes?: Record<string, AppleTheme>;
     motion?: Motion;
+    ripple?: boolean;
     glass?: Partial<AppleGlassSettings>;
     persist?: boolean;
     storageKey?: string;
@@ -362,6 +363,16 @@ export declare function createApple(options?: AppleOptions): import("vue").Raw<{
         reduced: boolean;
         set: (mode: Motion) => void;
     }>;
+    ripple: Ref<{
+        enabled: boolean;
+        set: (enabled: boolean) => void;
+    }, {
+        enabled: boolean;
+        set(enabled: boolean): void;
+    } | {
+        enabled: boolean;
+        set: (enabled: boolean) => void;
+    }>;
     glass: Ref<{
         set: (value: Partial<AppleGlassSettings>) => void;
         reset: () => void;

package/dist/core/overlay-surface.d.ts

@@ -0,0 +1,6 @@
+import type { ObjectDirective } from 'vue';
+/** The browser's top layer escapes clipping and transformed containing blocks
+ * without moving Vue's DOM, focus scope, or inherited theme out of its owner. */
+export declare function showOverlaySurface(element: HTMLElement): void;
+export declare function hideOverlaySurface(element: HTMLElement): void;
+export declare const OverlaySurface: ObjectDirective<HTMLElement>;

package/dist/core/popup-motion.d.ts

@@ -2,11 +2,11 @@ import { type VNode, type VNodeChild } from 'vue';
 export declare function freezePopup(element: Element): number | undefined;
 export declare function finishPopup(element: HTMLElement): void;
 export declare function resetPopup(element: Element): void;
-export declare function preparePopup(element: Element, reveal: boolean, interrupted?: number): void;
-/** One scalar controls visibility. Reproject it when placement changes so an
- * in-flight reveal/reversal never keeps the opening side's clip or translation. */
-export declare function animatePopup(element: Element, opened: boolean, done: () => void, reveal?: boolean): void;
-/** Shared field transition keeps the full panel layout stable during clipping. */
+export declare function preparePopup(element: Element, interrupted?: number): void;
+/** Animate the complete surface, including its shadow. Keep the current frame
+ * until its replacement is ready, including on reversal and placement changes. */
+export declare function animatePopup(element: Element, opened: boolean, done: () => void): void;
+/** Shared field transition keeps the full panel layout stable during motion. */
 export declare function popupTransition(content: VNodeChild, name?: string, persisted?: boolean, gap?: number): VNode<import("vue").RendererNode, import("vue").RendererElement, {
     [key: string]: any;
 }>;

package/dist/core/popup-placement.d.ts

@@ -19,9 +19,10 @@ interface PopupPositionOptions {
     fixed?: boolean;
     gap?: number;
 }
-/** Keep the DOM node, not a component ref: Vue clears refs before leave finishes. */
+/** Keep measurements in viewport coordinates and never uncap a live scrollport
+ * to measure it: doing so clamps scrollTop to zero before constraints return. */
 export declare function createPopupPositioner(panel: HTMLElement, options: PopupPositionOptions): PopupPositioner;
-/** Inline field popups stay attached to their anchor; placement is live through leave. */
+/** Field popups retain their DOM/focus owner while rendering in the top layer. */
 export declare function updateFieldPopup(element: HTMLElement): void;
 export declare function unmountFieldPopup(element: HTMLElement): void;
 export declare function mountFieldPopup(element: HTMLElement, gap?: number): void;

package/dist/index.d.ts

@@ -272,6 +272,7 @@ export declare const components: {
         disposeLayer: (() => void) | null;
         isTop: boolean;
         depth: number;
+        present: boolean;
     }, {
         resolvedMotion(): string;
     }, {
@@ -418,6 +419,7 @@ export declare const components: {
         disposeLayer: (() => void) | null;
         isTop: boolean;
         depth: number;
+        present: boolean;
     }, {
         resolvedMotion(): string;
     }, {
@@ -564,6 +566,7 @@ export declare const components: {
         disposeLayer: (() => void) | null;
         isTop: boolean;
         depth: number;
+        present: boolean;
     }, {
         resolvedMotion(): string;
     }, {
@@ -799,13 +802,13 @@ export declare const components: {
         internalOpen: boolean;
         depth: number;
         isTop: boolean;
+        present: boolean;
         disposeLayer: (() => void) | null;
         disposePosition: (() => void) | null;
         hoverTimer: ReturnType<typeof setTimeout> | null;
         positioned: boolean;
         positioner: import("./core/popup-placement").PopupPositioner | null;
         positionPanel: HTMLElement | null;
-        interruptedPopup: number | undefined;
     }, {
         opened(): boolean;
     }, {
@@ -2352,51 +2355,6 @@ export declare const components: {
         threshold: number;
         backTop: boolean;
     }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
-    AppleMarquee: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
-        text: {
-            type: StringConstructor;
-            default: string;
-        };
-        duration: {
-            type: NumberConstructor;
-            default: number;
-        };
-        paused: BooleanConstructor;
-        label: {
-            type: StringConstructor;
-            default: string;
-        };
-        motion: {
-            type: import("vue").PropType<"auto" | "full" | "reduced" | "none" | "inherit">;
-            default: string;
-        };
-    }>, {}, {
-        userPaused: boolean;
-    }, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
-        text: {
-            type: StringConstructor;
-            default: string;
-        };
-        duration: {
-            type: NumberConstructor;
-            default: number;
-        };
-        paused: BooleanConstructor;
-        label: {
-            type: StringConstructor;
-            default: string;
-        };
-        motion: {
-            type: import("vue").PropType<"auto" | "full" | "reduced" | "none" | "inherit">;
-            default: string;
-        };
-    }>> & Readonly<{}>, {
-        text: string;
-        duration: number;
-        label: string;
-        motion: "auto" | "full" | "reduced" | "none" | "inherit";
-        paused: boolean;
-    }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
     AppleStatistic: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
         value: {
             type: (NumberConstructor | StringConstructor)[];
@@ -4105,6 +4063,16 @@ export declare const components: {
                 reduced: boolean;
                 set: (mode: import(".").Motion) => void;
             }>;
+            ripple: import("vue").Ref<{
+                enabled: boolean;
+                set: (enabled: boolean) => void;
+            }, {
+                enabled: boolean;
+                set(enabled: boolean): void;
+            } | {
+                enabled: boolean;
+                set: (enabled: boolean) => void;
+            }>;
             glass: import("vue").Ref<{
                 set: (value: Partial<import(".").AppleGlassSettings>) => void;
                 reset: () => void;
@@ -4442,6 +4410,16 @@ export declare const components: {
                 reduced: boolean;
                 set: (mode: import(".").Motion) => void;
             }>;
+            ripple: import("vue").Ref<{
+                enabled: boolean;
+                set: (enabled: boolean) => void;
+            }, {
+                enabled: boolean;
+                set(enabled: boolean): void;
+            } | {
+                enabled: boolean;
+                set: (enabled: boolean) => void;
+            }>;
             glass: import("vue").Ref<{
                 set: (value: Partial<import(".").AppleGlassSettings>) => void;
                 reset: () => void;
@@ -4787,6 +4765,16 @@ export declare const components: {
                 reduced: boolean;
                 set: (mode: import(".").Motion) => void;
             }>;
+            ripple: import("vue").Ref<{
+                enabled: boolean;
+                set: (enabled: boolean) => void;
+            }, {
+                enabled: boolean;
+                set(enabled: boolean): void;
+            } | {
+                enabled: boolean;
+                set: (enabled: boolean) => void;
+            }>;
             glass: import("vue").Ref<{
                 set: (value: Partial<import(".").AppleGlassSettings>) => void;
                 reset: () => void;
@@ -5086,7 +5074,7 @@ export declare const components: {
     }, true, {}, any>;
     AppleButton: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
         variant: {
-            type: import("vue").PropType<"primary" | "secondary" | "outline" | "ghost" | "danger">;
+            type: import("vue").PropType<"primary" | "secondary" | "outline" | "danger">;
             default: string;
         };
         size: {
@@ -5113,7 +5101,7 @@ export declare const components: {
         };
     }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "click"[], "click", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
         variant: {
-            type: import("vue").PropType<"primary" | "secondary" | "outline" | "ghost" | "danger">;
+            type: import("vue").PropType<"primary" | "secondary" | "outline" | "danger">;
             default: string;
         };
         size: {
@@ -5145,55 +5133,120 @@ export declare const components: {
         disabled: boolean;
         iconOnly: boolean;
         loading: boolean;
-        variant: "secondary" | "danger" | "primary" | "outline" | "ghost";
+        variant: "secondary" | "danger" | "primary" | "outline";
         ripple: boolean;
         type: "reset" | "submit" | "button";
         motion: import(".").ComponentMotion;
     }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
     AppleLink: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+        as: {
+            type: import("vue").PropType<"a" | "button">;
+            default: string;
+        };
         href: StringConstructor;
         external: BooleanConstructor;
         disabled: BooleanConstructor;
-    }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+        icon: import("vue").PropType<import("vue").Component>;
+        iconOnly: BooleanConstructor;
+        label: StringConstructor;
+    }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, "click"[], "click", import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+        as: {
+            type: import("vue").PropType<"a" | "button">;
+            default: string;
+        };
         href: StringConstructor;
         external: BooleanConstructor;
         disabled: BooleanConstructor;
-    }>> & Readonly<{}>, {
+        icon: import("vue").PropType<import("vue").Component>;
+        iconOnly: BooleanConstructor;
+        label: StringConstructor;
+    }>> & Readonly<{
+        onClick?: ((...args: any[]) => any) | undefined;
+    }>, {
         disabled: boolean;
+        iconOnly: boolean;
         external: boolean;
+        as: "a" | "button";
     }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
-    AppleCard: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
-        title: StringConstructor;
-        subtitle: StringConstructor;
-        text: StringConstructor;
-        eyebrow: StringConstructor;
+    AppleCard: {
+        new (...args: any[]): import("vue").CreateComponentPublicInstanceWithMixins<Readonly<import("vue").ExtractPropTypes<{
+            icon: import("vue").PropType<import("vue").Component | string>;
+            iconColor: StringConstructor;
+            title: StringConstructor;
+            subtitle: StringConstructor;
+            text: StringConstructor;
+            eyebrow: StringConstructor;
+            image: StringConstructor;
+            imageAlt: {
+                type: StringConstructor;
+                default: string;
+            };
+            href: StringConstructor;
+            zoom: {
+                type: import("vue").PropType<"big" | "small" | "none">;
+                default: string;
+            };
+            shadow: {
+                type: import("vue").PropType<"normal" | "static" | "focused" | "none">;
+                default: string;
+            };
+            motion: {
+                type: import("vue").PropType<import(".").ComponentMotion>;
+                default: string;
+            };
+        }>> & Readonly<{}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, import("vue").PublicProps, {
+            shadow: "none" | "static" | "normal" | "focused";
+            motion: import(".").ComponentMotion;
+            zoom: "none" | "big" | "small";
+            imageAlt: string;
+        }, true, {}, {}, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, {}, any, import("vue").ComponentProvideOptions, {
+            P: {};
+            B: {};
+            D: {};
+            C: {};
+            M: {};
+            Defaults: {};
+        }, Readonly<import("vue").ExtractPropTypes<{
+            icon: import("vue").PropType<import("vue").Component | string>;
+            iconColor: StringConstructor;
+            title: StringConstructor;
+            subtitle: StringConstructor;
+            text: StringConstructor;
+            eyebrow: StringConstructor;
+            image: StringConstructor;
+            imageAlt: {
+                type: StringConstructor;
+                default: string;
+            };
+            href: StringConstructor;
+            zoom: {
+                type: import("vue").PropType<"big" | "small" | "none">;
+                default: string;
+            };
+            shadow: {
+                type: import("vue").PropType<"normal" | "static" | "focused" | "none">;
+                default: string;
+            };
+            motion: {
+                type: import("vue").PropType<import(".").ComponentMotion>;
+                default: string;
+            };
+        }>> & Readonly<{}>, {}, {}, {}, {}, {
+            shadow: "none" | "static" | "normal" | "focused";
+            motion: import(".").ComponentMotion;
+            zoom: "none" | "big" | "small";
+            imageAlt: string;
+        }>;
+        __isFragment?: never;
+        __isTeleport?: never;
+        __isSuspense?: never;
+    } & import("vue").ComponentOptionsBase<Readonly<import("vue").ExtractPropTypes<{
         icon: import("vue").PropType<import("vue").Component | string>;
         iconColor: StringConstructor;
-        image: StringConstructor;
-        imageAlt: {
-            type: StringConstructor;
-            default: string;
-        };
-        href: StringConstructor;
-        zoom: {
-            type: import("vue").PropType<"big" | "small" | "none">;
-            default: string;
-        };
-        shadow: {
-            type: import("vue").PropType<"normal" | "static" | "focused" | "none">;
-            default: string;
-        };
-        motion: {
-            type: import("vue").PropType<import(".").ComponentMotion>;
-            default: string;
-        };
-    }>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
         title: StringConstructor;
         subtitle: StringConstructor;
         text: StringConstructor;
         eyebrow: StringConstructor;
-        icon: import("vue").PropType<import("vue").Component | string>;
-        iconColor: StringConstructor;
         image: StringConstructor;
         imageAlt: {
             type: StringConstructor;
@@ -5212,12 +5265,24 @@ export declare const components: {
             type: import("vue").PropType<import(".").ComponentMotion>;
             default: string;
         };
-    }>> & Readonly<{}>, {
+    }>> & Readonly<{}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, {
         shadow: "none" | "static" | "normal" | "focused";
         motion: import(".").ComponentMotion;
         zoom: "none" | "big" | "small";
         imageAlt: string;
-    }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+    }, {}, string, {}, import("vue").GlobalComponents, import("vue").GlobalDirectives, string, import("vue").ComponentProvideOptions> & import("vue").VNodeProps & import("vue").AllowedComponentProps & import("vue").ComponentCustomProps & (new () => {
+        $slots: {
+            media?: (props: {}) => any;
+        } & {
+            icon?: (props: {}) => any;
+        } & {
+            title?: (props: {}) => any;
+        } & {
+            default?: (props: {}) => any;
+        } & {
+            actions?: (props: {}) => any;
+        };
+    });
     AppleImage: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
         preview: {
             type: BooleanConstructor;

package/docs/COMPONENTS.md

@@ -4,7 +4,7 @@
 
 ## 公共约定
 
-`secondary` 与 `outline` 都是描边按钮，`ghost` 是纯文字按钮且始终不启用 Ripple。所有 API 可直接从 JavaScript 和普通 Vue `<script>` 使用，TypeScript 不是消费前提。
+`secondary` 与 `outline` 都是描边按钮，纯文字操作使用 `AppleLink`，始终不启用 Ripple。所有 API 可直接从 JavaScript 和普通 Vue `<script>` 使用，TypeScript 不是消费前提。
 
 Tabs、TabBar、SegmentedControl、DatePicker 日期/时间页签均不使用 Ripple；保留选中指示器位移与内容切换动画。
 
@@ -15,6 +15,18 @@ Tabs、TabBar、SegmentedControl、DatePicker 日期/时间页签均不使用 Ri
 - 内容选项类型为 `AppleItem = { label; value; disabled?; description?; href?; content? }`；`value` 为唯一的 `string | number`。
 - 组件并非 Vuetify 同名组件的透传包装。只依赖这里声明的接口，不假设任意 `v-*` prop、slot 或事件都可直接使用。
 
+## Glass 通用样式
+
+导入 `apptify/style.css` 后，在 `<apple-provider>` 内给自定义元素添加 `.apple-glass`，即可应用跟随主题和全局 glass 设置的背景、文字颜色与背景模糊：
+
+```vue
+<apple-provider>
+  <div class="apple-glass">自定义玻璃面板</div>
+</apple-provider>
+```
+
+该类只提供材质与文字颜色，间距、圆角、边框和阴影由使用方设置。Provider 外使用默认浅色材质；Provider 内跟随 `glass.opacity` 与 `glass.blur` 配置。
+
 ## 动效组件 · 2
 
 | 组件 | Props | 说明 |
@@ -24,16 +36,16 @@ Tabs、TabBar、SegmentedControl、DatePicker 日期/时间页签均不使用 Ri
 
 全局入场使用 `v-apple-entrance="pageKey"` 放在一个页面容器上：首次挂载及 key 改变时整体由下向上 14px，不复制旧页、不执行离场、不改变透明度。不应嵌套应用到同一页面的多层内容。
 
-另提供 `v-apple-ripple` 和 `v-apple-selection`；后者移动到后代 `[data-apple-selected="true"]`，也可传 `{selector}`。全局 none/reduced 与系统减少动态效果限制同样生效。
+另提供 `v-apple-ripple` 和 `v-apple-selection`；后者移动到后代 `[data-apple-selected="true"]`，也可传 `{selector}`。selection 遵循全局 none/reduced 与系统减少动态效果限制；ripple 在减弱动效下可手动开启，none 下始终禁用。
 
 ## 基础组件 · 9
 
 | 组件 | 主要 Props | Events / Slots / 说明 |
 | --- | --- | --- |
 | `AppleProvider` | `theme?: string`、`motion?: auto/full/reduced/none` | default slot；应用主题并自动挂载弹层宿主。无显式属性时复用插件上下文。 |
-| `AppleButton` | M；`variant=primary`（primary/secondary/outline/ghost/danger）、`size=medium`（small/medium/large）、`icon: Component`、`iconOnly`、`label`、`disabled`、`loading`、`ripple=true`、`href`、`type=button` | `click(event)`；default slot。纯图标按钮须提供 label。只有允许完整动效时启用 Ripple。 |
-| `AppleLink` | `href`、`external`、`disabled` | default slot；external 使用新窗口并设置 `noopener noreferrer`。 |
-| `AppleCard` | M；`title`、`subtitle`、`text`、`eyebrow`、`icon: Component 或图片 URL`、`iconColor`、`image`、`imageAlt`、`href`、`zoom=small`（big/small/none）、`shadow=normal`（normal/static/focused/none） | default、media、icon、title、actions slots；href 为标题链接，不会把所有嵌套控件变成一个大按钮。 |
+| `AppleButton` | M；`variant=primary`（primary/secondary/outline/danger）、`size=medium`（small/medium/large）、`icon: Component`、`iconOnly`、`label`、`disabled`、`loading`、`ripple=true`、`href`、`type=button` | `click(event)`；default slot；图标位于文字右侧。纯图标按钮须提供 label。关闭动效时禁用 Ripple，其余模式遵循全局波纹开关。 |
+| `AppleLink` | `as=a`（a/button）、`href`、`external`、`disabled`、`icon`、`iconOnly`、`label` | default slot；文字操作使用 as=button；external 使用新窗口并设置 `noopener noreferrer`。 |
+| `AppleCard` | M；`title`、`subtitle`、`text`、`eyebrow`、`icon: Component 或图片 URL`、`iconColor`、`image`、`imageAlt`、`href`、`zoom=none`（big/small/none）、`shadow=normal`（normal/static/focused/none） | default、media、icon、title、actions slots；href 为标题链接，不会把所有嵌套控件变成一个大按钮。 |
 | `AppleImage` | M；`gallery: AppleImageItem | (string/AppleImageItem)[]`（唯一来源，默认空数组，单图可传对象）；`preview=true`、`carousel=false`、`disabled=false`、`label`、`galleryLayout=compact`（compact/tiled/tiled-wrap，所有设备）、`galleryShape=natural`（natural/square）、`index=0`、`squared`、`aspectRatio='4/3'`、`fit=cover`（cover/contain） | caption 与 item({item,index,active}) slots；carousel 强制 compact、常显控件且保留自由滚动；默认点击预览；统一入口，按触屏能力选择预览交互；完整渲染图片组，compact 在固定框内横滑，桌面触控板支持自由连续横滑、一次手势可跨越多张，快速点击翻页延续当前位置和速度；hover 不缩放，多图显示左右翻页按钮（单图小窗与全屏均无翻页箭头），跨多张点击小点时直接衔接当前画面与目标图并支持连续改选，tiled 等高横向平铺，溢出时底部常显自定义滚动条，支持拖动、点击轨道与键盘，滑块比例随内容和容器尺寸同步，tiled-wrap 等宽保留图片比例，按列从上往下紧密堆叠，避免按行对齐产生空白；平铺 hover 只缩放当前图片；galleryShape=square 强制 1:1 并居中裁剪（覆盖 fit），squared 同样作用于图片组；`update:index`、`change(index)`；图片错误状态；squared 覆盖 aspectRatio。 |
 | `AppleSearch` | `v-model: string`、`placeholder='搜索'`、`label='搜索'`、`disabled` | `search(value)` 在 Enter 时发出；清空更新 model。 |
 | `AppleContainer` | `width=1200`（number/string） | default slot；数字宽度按 px，宽度不会超过可用空间。 |
@@ -42,15 +54,17 @@ Tabs、TabBar、SegmentedControl、DatePicker 日期/时间页签均不使用 Ri
 
 ## 表单组件 · 18
 
+字段名称、hint、错误提示和行内空白只用于展示，点击不会聚焦、展开或切换控件；直接操作输入框、选择器或开关本身。字段名称通过 ARIA 保留可访问性关联。
+
 | 组件 | 主要 Props | Events / Slots / 方法 |
 | --- | --- | --- |
 | `AppleInput` | F；`v-model: string/number`、`type=text`、`placeholder`、`clearable` | `change(value)`、`clear()`；prefix/suffix slots；`focus()`；输入事件实际返回字符串。password 类型带显隐按钮。 |
 | `AppleTextarea` | F；`v-model: string`、`placeholder`、`rows=4`、`maxlength`、`counter`、`resize=true` | `change(value)`；`focus()`；resize=true 允许纵向缩放。 |
 | `AppleSelect` | F；`v-model: string/number/null`、`items: AppleOption[]`、`placeholder='请选择'` | `change(value)`；自绘半透明模糊下拉，支持键盘导航和 required 校验。 |
 | `AppleAutocomplete` | F；`v-model: string/number/null`、`items`、`placeholder`、`emptyText`、`clearable=true`、`filter(query,item)` | `change(value)`、`search(query)`；`focus()`；方向键/Enter/Escape；是单选过滤，不是多选标签输入。 |
-| `AppleCheckbox` | F；`v-model: boolean`、`indeterminate` | `change(checked)`；default slot 替代 label 文本。 |
+| `AppleCheckbox` | F；`v-model: boolean`、`indeterminate` | `change(checked)`；default slot 替代 label 文本，默认文字在左、开关在右；hint 在下方。 |
 | `AppleRadioGroup` | F；`v-model: string/number/null`、`items`、`inline`、`name` | `change(value)`；原生 radio group。 |
-| `AppleSwitch` | F；`v-model: boolean` | `change(checked)`；default slot 替代 label 文本。 |
+| `AppleSwitch` | F；`v-model: boolean` | `change(checked)`；default slot 替代 label 文本。默认 width: 100%，label 和 hint 在左侧同一列，开关在右侧。 |
 | `AppleSlider` | F；`v-model: number`、`min=0`、`max=100`、`step=1`、`showValue=true`、`formatValue(value)` | `change(value)`；单值原生 range，不是双滑块范围选择。 |
 | `AppleStepper` | F；`v-model: number`、`min=-Infinity`、`max=Infinity`、`step=1` | `change(value)`；减/加按钮及可编辑数值输入；提交时约束范围。 |
 | `AppleSegmentedControl` | F；`v-model: string/number/null`、`items`、`name` | `change(value)`；基于 radio 的单选分段控件，不是 tabs 内容容器。 |
@@ -58,7 +72,7 @@ Tabs、TabBar、SegmentedControl、DatePicker 日期/时间页签均不使用 Ri
 | `AppleColorPicker` | F；`v-model: string='#0071e3'`、`showValue=true` | `change(value)`；自绘色板和 HEX 输入，不打开原生颜色弹窗。 |
 | `AppleUpload` | F；`v-model: File[]`、`accept`、`multiple`、`maxSize=Infinity`、`maxFiles=Infinity`、`capture=user/environment`、`buttonText` | `change(files)`、`reject({file,reason}[])`、`remove(file)`；default slot；maxSize 单位为字节；不发送网络请求。 |
 | `AppleForm` | M；`disabled`、`loading`、`validator(FormData): boolean/string/Promise` | `submit(FormData)`、`invalid({type,message?})`、`reset()`；default slot `{loading}`；实例方法 `validate(): Promise<boolean>`、`submit()`、`reset()`。 |
-| `AppleFormField` | F；`for` | default slot `{id,disabled,required,'aria-invalid','aria-describedby'}`；用于关联自定义输入及提示。 |
+| `AppleFormField` | F；`for` | default slot `{id,disabled,required,'aria-label','aria-labelledby','aria-invalid','aria-describedby'}`；将 slot 属性绑定到自定义输入，以关联字段名称及提示。 |
 | `AppleOtpInput` | F；`label='验证码'`、`v-model: string`、`length=6`（1–12）、`numeric=true`、`name`、`mask` | `change(value)`、`complete(value)`；`focus(index=0)`；支持粘贴、退格、方向键与验证码自动填充提示。 |
 | `AppleCascader` | F；`v-model: (string/number)[]`、`items: AppleCascaderOption[]`、`placeholder`、`levelLabels: string[]`、`name` | `change(path)`、`complete(path)`；选项递归增加 `children`；不内置行政区划数据。 |
 | `AppleRate` | F；`label='评分'`、`v-model: number`、`max=5`（渲染 1–10）、`readonly`、`allowClear=true`、`name` | `change(value)`；整数星级；allowClear 时再次选择当前值返回 0；不支持半星。 |
@@ -111,7 +125,6 @@ validator 返回 `true` 才通过；字符串作为错误信息，`false` 显示
 | `AppleInfiniteScroll` | `loading`、`error: boolean/string`、`finished`、`disabled`、`distance=120`、`finishedText` | `load(done)`、`retry(done)`；default slot；IntersectionObserver 及手动加载按钮；完成后调用 done，或令 loading 从 true 回到 false。 |
 | `AppleBackTop` | `target: CSS selector=''`、`threshold=300`、`label`、`disabled` | `click(event)`；default slot；空 target 使用 window，达到滚动阈值才显示。 |
 | `AppleFloatingGroup` | `backTop=true`、`threshold=300`、`target`、`label` | default slot 放附加操作，回顶按钮始终排最下；默认固定右下并考虑安全区。 |
-| `AppleMarquee` | `text`、`duration=24`、`paused`、`label` | default slot；duration 单位为秒；带暂停按钮；减少动态效果时停止连续滚动。 |
 | `AppleStatistic` | 必填 `label`；`value: string/number`、`prefix`、`suffix`、`precision=0`、`locale=zh-CN`、`description` | default slot；数值本地化格式，不会自动请求统计数据。 |
 
 `AppleColumn = { key: string; label: string; sortable?: boolean; align?: 'left'|'center'|'right'; width?: number|string; minWidth?: number; maxWidth?: number; resizable?: boolean }`。表格 rows 应提供稳定唯一的 `rowKey`。
@@ -190,6 +203,7 @@ Modal slots：`title`、default `{close}`、footer `{close,confirm,cancel}`。
 | `overlays.entries.value` | 当前弹层列表，`Ref<OverlayEntry[]>`。 |
 | `portalTarget.value` | 弹层挂载 DOM 元素。 |
 | `motion.value.set(mode)` | 即时修改全局动效策略。 |
+| `ripple.value.enabled / set(enabled)` | 全局点击波纹开关，默认 true；也可传入 `createAppleUI({ ripple: false })`。切换到减弱动效或系统开启减少动态效果时自动关闭，可手动开启；只有关闭动效时禁止开启。开启 persist 时保存偏好，嵌套 Provider 共享此开关。 |
 | `onMessage(channel,listener)` | 注册监听器，返回取消订阅函数。 |
 | `sendMessage(channel,payload?)` | 返回该 channel 全部监听器的返回值数组。 |
 | `dialog(options)` | 打开 dialog 并返回独立句柄。 |

package/docs/INPUT-WORKSHOP.md

@@ -0,0 +1,59 @@
+# AppleInput API 页面样板
+
+当前验收入口：<http://127.0.0.1:5201/component-docs/apple-input>。也可以从组件总览的 AppleInput 卡片底部 AppleLink「代码与 API」进入。第一阶段只注册 AppleInput，未扩面、未提交、未发布，404 与已有工作保持原样。
+
+## 当前交互
+
+- 独立页面，顶部使用 AppleBreadcrumbs；四边 padding 统一40px。顶部组件演示、左侧 AppleTree 列出全部属性、事件、插槽和方法，点击定位并高亮；支持键盘展开/折叠，不再显示单独的 API tab。总览入口与相邻展开栏的高度、字号、字重、颜色和padding一致。
+- 17 条公开接口：11 个 props、3 个 events、2 个 slots、focus() 方法。均有源码核实的类型、默认值（适用时）、解释和行为边界。
+- 示例按需提供。Vue 原生 v-model 与原生 placeholder 只解释，不另做专门示例；15 个组件相关例子通过 AppleAccordion 展开。
+- 示例标题、功能和操作说明全部放在 Accordion 的展开内容内。
+- 桌面左侧效果、右侧 Vue SFC；720px 以下上下排列。三项输入类型使用 AppleSegmentedControl；五项动效模式使用 AppleSelect，状态切换使用 AppleSwitch，示例容器使用 AppleCard，操作使用 AppleButton。
+- API 文档按页面加载；编译器、CodeMirror、运行资源直到展开示例才加载。任意时刻只有一个编辑器与 iframe，折叠/切换销毁实例，草稿仅保存本页内代码文本，离开页面丢弃。恢复示例返回原始文本。
+- 移除了组件源码编辑 tab。源码提取工具与可选 implementation 契约保留供后续确需源码的示例使用，当前页面不下载源码快照。
+
+## 可复用边界
+
+`playground/editor/contract.ts` 定义 ComponentDocument：name/source、props/events/slots/methods/notes。ApiEntry 必须提供 id/name/type/description，default 与完整 SFC example 可选。不要为了填满页面给所有原生 API 制作重复示例。
+
+`playground/editor/documents.ts` 是轻量注册表，每项提供名称、标签、分组、说明、异步文档 loader，以及可选预览组件。组件总览根据注册表自动显示文档入口；没有注册的组件保持原来的展开区。
+
+`playground/views/component-docs/[component].vue` 是共用文件路由：根据 slug 读取注册表、加载文档、生成导航与演示。没有 AppleInput 的专属布局逻辑，也不依赖总览的 ComponentDemo/catalog。删除总览及其演示文件时，独立文档仍可构建。
+
+`ComponentDocumentLink.vue` 只负责卡片底部 AppleLink 与 Vue Router 导航。`ComponentWorkshop.vue` 接收 doc prop，统一渲染 API、Accordion、单个活动示例和文本草稿。`LiveVueEditor.vue` 只接收 files、activeFile、baselineFiles，负责官方 REPL、主题、恢复/复制和错误显示。
+
+后续接入步骤：从组件真实源码列举接口 → 编写符合契约的文档和必要 SFC 例子 → 提供可选轻量预览 → 注册 slug。页面/入口/编辑器不需要复制或重写。当前注册表只含 AppleInput，待样板验收后再按组件分块实施。
+
+## 编译方案、依赖与资源
+
+使用 [Vue 官方 @vue/repl](https://github.com/vuejs/repl) 4.7.2、官方 CodeMirror、useStore/Sandbox/compiler-sfc。不自造正则编译器。用户代码在本地浏览器编译，不上传第三方。支持 template、script setup、普通 CSS/scoped CSS、响应式状态及组件库 ESM 导入。
+
+[Vuetify Play](https://play.vuetifyjs.com/) 作为交互依据；已检查官方发布页面/入口，使用 Vue REPL 与异步 MonacoWrapper。本样板选择较轻的官方 CodeMirror，避免 Monaco 的额外 CDN 类型加载。
+
+开发依赖：固定 @vue/repl 4.7.2、es-module-shims ^2.8.4、esbuild ^0.25.12、postcss ^8.5.28；esbuild/PostCSS 原已作为传递依赖安装，现声明为构建工具直接依赖。未升级无关依赖，不加入组件库生产入口。
+
+当前生产 gzip 约：文档数据 4.8KB；共享路由 JS/CSS 3.8KB；展开时编辑器/compiler/CodeMirror JS 417.6KB、CSS 4.3KB；预览 Vue 41.9KB、Apptify runtime 79.6KB、库 CSS 16.2KB、shim 23KB。展开新增约583KB gzip。额外 TS/JSX 转换块约1.05MB gzip，仅相关语法触发时加载。下载缓存关闭后仍保留，运行实例销毁。
+
+`tooling/playground-editor.mjs` 将本地库及依赖打包为浏览器 ESM，Vue 单独映射；消费者使用公开 apptify/apptify/style.css，不依赖仓库外路径。模板同步包含注册表、页面、共享编辑器、预览与文档数据。Vite dev/preview 自动给 assets/editor/* 添加公开资源 CORS；静态部署也需设置这些资源的 CORS。
+
+## 隔离与限制
+
+固定版本 REPL 的 sandbox 收紧为 allow-scripts，其余权限删除，上游结构变化时构建失败，未改官方编译器。opaque iframe 隔离父文档/存储及预览 CSS，普通编译/运行错误在编辑器中展示。CSP 默认禁止资源，允许 inline/blob/本机运行资源；不自动解析任意 npm、不请求 CDN。严格父 CSP 需要兼容 srcdoc、inline 模块与 blob；本样板不修改父服务器策略。
+
+iframe 可能共享浏览器进程，同步死循环、超大编译输入、内存耗尽仍可能卡住标签页；刷新可恢复，不能承诺完全隔离。CSP 允许当前 origin 请求，不隔离同源 API 副作用，不运行不可信代码。无 Sass/Less、任意 npm 解析、服务端 API 与文件系统。
+
+真实表单导航被禁用；required 例子使用原生 reportValidity() 模拟提交校验。重新编译会 unmount 旧 Vue 应用，代码创建的资源须在 onUnmounted 清理；重新运行重建 iframe，折叠/离开销毁运行 realm。auto-resize=false 避免上游每次 mount 额外注册未清理的 resize handler；CodeMirror 自身一次性共享处理器保留。
+
+用户截图中的 import map 报错已修复：useStore 之前同步建立文件/map，以 App.vue 开始编译再切换活动文件，设置 welcomeSFC 防止官方默认欢迎页替换入口。恢复带完整 map 并串行应用。
+
+## 验证
+
+`tests/e2e/input-workshop.spec.ts` 验证总览底部 AppleLink 导航、直接访问文档路由、无多余 tab、面包屑、40px padding、相邻底栏样式一致性、17 个接口/15 个 Accordion、展开前无编辑器/编译器资源、同一时间一个编辑器、每个例子的实际组件显示、代码修改、编译/运行错误恢复、清空、required/focus、草稿保留/恢复、反复运行、dark 主题、桌面左右/手机上下几何位置、390px 无溢出、折叠/离开销毁。最终生产回归14.6秒通过，pageErrors为空。文档页DOM：展开前441 → 展开764 → 折叠447；编辑器与iframe均为0 → 1 → 0。折叠后保留下载资源缓存。
+
+最新截图和原始 DOM/资源数据：`artifacts/input-workshop/api-page-desktop.png`、`api-page-mobile.png`、`metrics-v3.json`。早期弹窗证据保留为历史记录，不代表当前界面。
+
+类型检查、生产构建、消费者完整模板/删减模板与库消费验证通过；归档验证目录为`/var/folders/y3/wc0kb5h13yl41wyj6nrf3vv00000gp/T/apptify-package-9m8mVc`。早期全库单元测试179通过、1个既有404动画frames失败；按要求未修改该内容。
+
+所有接口与示例说明改用直白中文：先说明用途与操作，再解释必要的边界。树形导航和正文共用 sections.ts 分组契约，不需要逐页维护导航节点。
+
+预览动效跟随页面设置，并通过组件库上下文监听系统减少动效偏好。预览根节点应用与 AppleProvider 一致的公共样式和解析后的动效模式；卸载时停止偏好监听。Playwright 验证 full 模式下分段切换存在实际动画，none 模式下没有运行中的动画。