weifuwu 0.37.0 → 0.38.0

package/README.md

@@ -23,7 +23,7 @@ npm install weifuwu
 | **ui** | `weifuwu` | SSR 渲染 + 动态 JS/CSS 编译 → `ctx.ui` | `Router` |
 | **graphql** | `weifuwu` | GraphQL 端点 | `Router` |
 | **client** | `weifuwu/client` | 前端 VDOM + Proxy 框架 + i18n + ErrorBoundary | — |
-| **components** | `weifuwu/components` | 34 个 HTML 原语组件（Button/Table/Modal/...） | `client` |
+| **components** | `weifuwu/components` | 36 个 HTML 原语组件（Button/Table/Modal/...） | `client` |
 | **layout** | `weifuwu/layout` | 纯 CSS 布局原语 + 主题 Token | — |
 
 ---
@@ -526,6 +526,51 @@ ctx.i18n?.setLocale('en-US')    // → 自动触发重渲染
 import { i18n, zhCN, enUS } from 'weifuwu/client'
 ```
 
+### confirm —— 确认对话框
+
+```ts
+import { createApp, confirm } from 'weifuwu/client'
+
+createApp()
+  .use(confirm())
+  .mount('#root', App)
+
+// 在组件中使用
+async function handleDelete(ctx: WfuiContext) {
+  const ok = await ctx.confirm?.('确定删除？', {
+    title: '确认',
+    confirmText: '删除',
+    cancelText: '取消',
+    variant: 'danger',  // 'default' | 'danger'
+  })
+  if (ok) { /* 执行 */ }
+}
+```
+
+- 直接 DOM 渲染（不依赖 VDOM）
+- 返回 `Promise<boolean>` — `await ctx.confirm(msg, opts?)`
+- 自动锁定背景滚动（ScrollLock）
+- ESC / 点击遮罩关闭
+
+### ScrollLock / FocusTrap 工具
+
+```ts
+import { lockScroll, unlockScroll } from 'weifuwu/client'
+import { trapFocus } from 'weifuwu/client'
+
+// 锁定/解锁滚动（支持嵌套计数）
+lockScroll()
+unlockScroll()
+
+// 焦点陷阱，返回 cleanup 函数
+const cleanup = trapFocus(containerEl)
+// 组件卸载时
+cleanup()  // 恢复焦点
+```
+
+- `lockScroll()`: 多层级可嵌套锁定，iOS Safari `position:fixed` 兼容
+- `trapFocus(el)`: Tab/Shift+Tab 在容器内循环，restore 之前焦点
+
 ### 前端类型
 
 `VNode`, `VNodeType`, `Component`, `WfuiContext`, `AppMiddleware`, `RouteDef`, `ApiClient`, `ApiOptions`, `ApiRequestOptions`, `ApiError`, `AuthClient`, `AuthOptions`, `ErrorBoundaryProps`, `I18nOptions`, `I18nState`, `LocalePackage`
@@ -645,7 +690,7 @@ document.documentElement.setAttribute('data-theme', 'dark')
 
 ## 组件库 — `weifuwu/components`
 
-29 个 **HTML 原语**，覆盖 90% 的 SaaS 页面 HTML 需求。每个组件是 `(props, ctx) => VNode` 纯函数，引用 `weifuwu/layout` 的 CSS 变量做主题。
+36 个 **HTML 原语**，覆盖 90% 的 SaaS 页面 HTML 需求。每个组件是 `(props, ctx) => VNode` 纯函数，引用 `weifuwu/layout` 的 CSS 变量做主题。
 
 ```ts
 import { Button, Input, Table, Modal, Toast } from 'weifuwu/components'
@@ -657,11 +702,10 @@ import 'weifuwu/components/style.css'
 | 类别 | 组件 | 用途 |
 |------|------|------|
 | **表单核心** | `Button` `Input` `Textarea` `Select` | 4 个最常用的表单元素 |
-| **表单核心** | `InputNumber` | 数字输入，带自定义步进按钮 (`showStepper`) |
 | **表单选择** | `Checkbox` `Switch` `RadioGroup` `Slider` | 选择类输入 |
 | **表单增强** | `Form` `Field` `FileUpload` `SearchInput` `ProgressBar` | 文件上传、搜索、进度 |
-| **数据展示** | `Table` `Card` `Badge` `Tag` `Avatar` `StatCard` `PageHeader` | 数据展示与页面标题 |
-| **数据反馈** | `Modal` `Drawer` `Tooltip` `Toast` `Alert` `Loading` `EmptyState` | 弹窗、抽屉、提示 |
+| **数据展示** | `Table` `Card` `Badge` `Tag` `Avatar` `StatCard` `PageHeader` `Img` | 数据展示与页面标题 |
+| **数据反馈** | `Modal` `Drawer` `Tooltip` `Popover` `Toast` `Alert` `Loading` `EmptyState` `Skeleton` | 弹窗、抽屉、弹出层、骨架屏 |
 | **导航组件** | `Breadcrumb` `Tabs` `Dropdown` `Pagination` `Steps` `Accordion` | 面包屑、标签页、分页 |
 | **布局** | `Divider` | 分割线 (水平/垂直/带文字) |
 

package/dist/client/confirm.d.ts

@@ -0,0 +1,26 @@
+/**
+ * weifuwu/client — Confirm 对话框
+ *
+ * 使用：
+ *   import { createApp, confirm } from 'weifuwu/client'
+ *
+ *   createApp()
+ *     .use(confirm())
+ *     .mount('#root', () => <App />)
+ *
+ *   // 页面中使用
+ *   if (await ctx.confirm?.('确定删除？')) {
+ *     // 执行删除
+ *   }
+ */
+import type { AppMiddleware } from './types.ts';
+export interface ConfirmOptions {
+    title?: string;
+    confirmText?: string;
+    cancelText?: string;
+    variant?: 'primary' | 'danger';
+}
+export interface ConfirmState {
+    confirm: (message: string, options?: ConfirmOptions) => Promise<boolean>;
+}
+export declare function confirm(): AppMiddleware;

package/dist/client/focus-trap.d.ts

@@ -0,0 +1,4 @@
+/**
+ * weifuwu/client — FocusTrap
+ */
+export declare function trapFocus(container: HTMLElement): () => void;

package/dist/client/index.d.ts

@@ -31,5 +31,9 @@ export { ErrorBoundary } from './error-boundary.ts';
 export type { ErrorBoundaryProps } from './error-boundary.ts';
 export { i18n } from './i18n.ts';
 export type { I18nOptions, I18nState } from './i18n.ts';
+export { lockScroll, unlockScroll } from './scroll-lock.ts';
+export { trapFocus } from './focus-trap.ts';
+export { confirm } from './confirm.ts';
+export type { ConfirmOptions, ConfirmState } from './confirm.ts';
 export { zhCN } from './locale/zh_CN.ts';
 export { enUS } from './locale/en_US.ts';

package/dist/client/index.js

@@ -71,6 +71,7 @@ function wrapDeep(val, dirty) {
 function createComponentProxy(target, dirty) {
   return new Proxy(target, {
     set(t, k, v) {
+      if (t[k] === v) return true;
       t[k] = wrapDeep(v, dirty);
       dirty();
       return true;
@@ -334,6 +335,14 @@ function normalize(children) {
   return result;
 }
 function patchSimpleChildren(parent, oldChildren, newChildren, ctx) {
+  for (let i = oldChildren.length - 1; i >= newChildren.length; i--) {
+    const oldChild = oldChildren[i];
+    const node = parent.childNodes[i];
+    if (node) {
+      callRefCleanup(oldChild);
+      node.remove();
+    }
+  }
   const max = Math.max(oldChildren.length, newChildren.length);
   for (let i = 0; i < max; i++) {
     const oldChild = oldChildren[i];
@@ -342,12 +351,7 @@ function patchSimpleChildren(parent, oldChildren, newChildren, ctx) {
     if (oldChild === void 0 && newChild !== void 0) {
       const node = renderValue(newChild, ctx);
       parent.appendChild(node);
-    } else if (newChild === void 0) {
-      if (existingNode) {
-        callRefCleanup(oldChild);
-        existingNode.remove();
-      }
-    } else {
+    } else if (oldChild !== void 0 && newChild !== void 0) {
       patchValue(parent, existingNode, oldChild, newChild, ctx);
     }
   }
@@ -909,8 +913,7 @@ var zhCN = {
     Switch: { ariaLabel: "\u5207\u6362" },
     Breadcrumb: { ariaLabel: "\u9762\u5305\u5C51" },
     Modal: { ariaLabel: "\u5F39\u7A97" },
-    Drawer: { ariaLabel: "\u4FA7\u8FB9\u9762\u677F" },
-    InputNumber: { increase: "\u589E\u52A0", decrease: "\u51CF\u5C11" }
+    Drawer: { ariaLabel: "\u4FA7\u8FB9\u9762\u677F" }
   }
 };
 
@@ -929,8 +932,7 @@ var enUS = {
     Switch: { ariaLabel: "Toggle" },
     Breadcrumb: { ariaLabel: "Breadcrumb" },
     Modal: { ariaLabel: "Dialog" },
-    Drawer: { ariaLabel: "Panel" },
-    InputNumber: { increase: "Increase", decrease: "Decrease" }
+    Drawer: { ariaLabel: "Panel" }
   }
 };
 
@@ -989,6 +991,145 @@ function deepMerge(a, b) {
   }
   return result;
 }
+
+// src/client/scroll-lock.ts
+var lockedCount = 0;
+var originalOverflow = "";
+var originalPosition = "";
+var originalTop = "";
+var originalWidth = "";
+var scrollY = 0;
+function canLock() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function lockScroll() {
+  lockedCount++;
+  if (lockedCount > 1) return;
+  if (!canLock()) return;
+  scrollY = window.scrollY;
+  const body = document.body;
+  originalOverflow = body.style.overflow;
+  originalPosition = body.style.position;
+  originalTop = body.style.top;
+  originalWidth = body.style.width;
+  body.style.overflow = "hidden";
+  const isIOS = /iPhone|iPad|iPod/.test(navigator.platform) || /Mac/.test(navigator.platform) && "ontouchend" in document;
+  if (isIOS) {
+    body.style.position = "fixed";
+    body.style.top = `-${scrollY}px`;
+    body.style.width = "100%";
+  }
+}
+function unlockScroll() {
+  lockedCount--;
+  if (lockedCount > 0) return;
+  if (!canLock()) return;
+  const body = document.body;
+  body.style.overflow = originalOverflow;
+  body.style.position = originalPosition;
+  body.style.top = originalTop;
+  body.style.width = originalWidth;
+  if (scrollY > 0) window.scrollTo(0, scrollY);
+}
+
+// src/client/focus-trap.ts
+var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+function trapFocus(container) {
+  const focusable = container.querySelectorAll(FOCUSABLE);
+  if (focusable.length === 0) return () => {
+  };
+  const first = focusable[0];
+  const last = focusable[focusable.length - 1];
+  const handler = (e) => {
+    if (e.key !== "Tab") return;
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  };
+  const prevFocused = document.activeElement;
+  first.focus();
+  container.addEventListener("keydown", handler);
+  return () => {
+    container.removeEventListener("keydown", handler);
+    prevFocused?.focus();
+  };
+}
+
+// src/client/confirm.ts
+function createConfirmModal(message, options) {
+  return new Promise((resolve) => {
+    const {
+      title = "\u786E\u8BA4\u64CD\u4F5C",
+      confirmText = "\u786E\u5B9A",
+      cancelText = "\u53D6\u6D88",
+      variant = "primary"
+    } = options;
+    const overlay = document.createElement("div");
+    overlay.className = "wf-modal";
+    overlay.style.cssText = "position:fixed;inset:0;z-index:10000;display:flex;align-items:center;justify-content:center";
+    const bg = document.createElement("div");
+    bg.style.cssText = "position:fixed;inset:0;background:rgba(0,0,0,0.4);z-index:-1";
+    const box = document.createElement("div");
+    box.style.cssText = `background:var(--wf-color-bg,#fff);border-radius:var(--wf-radius-md,8px);box-shadow:var(--wf-shadow-lg,0 4px 24px rgba(0,0,0,0.12));min-width:360px;max-width:90vw;z-index:1`;
+    if (title) {
+      const header = document.createElement("div");
+      header.style.cssText = "display:flex;align-items:center;justify-content:space-between;padding:16px 20px;border-bottom:1px solid var(--wf-color-border,#e5e7eb);font-family:var(--wf-font-sans);font-size:var(--wf-font-size-lg);font-weight:var(--wf-font-weight-semibold);color:var(--wf-color-text);line-height:1.4";
+      header.textContent = title;
+      box.appendChild(header);
+    }
+    const body = document.createElement("div");
+    body.style.cssText = "padding:20px;font-family:var(--wf-font-sans);font-size:var(--wf-font-size-sm);color:var(--wf-color-text);line-height:var(--wf-line-height-normal)";
+    body.textContent = message;
+    box.appendChild(body);
+    const footer = document.createElement("div");
+    footer.style.cssText = "display:flex;align-items:center;justify-content:flex-end;gap:8px;padding:12px 20px;border-top:1px solid var(--wf-color-border,#e5e7eb)";
+    const cancelBtn = document.createElement("button");
+    cancelBtn.className = "wf-btn wf-btn--secondary wf-btn--md";
+    cancelBtn.textContent = cancelText;
+    const confirmBtn = document.createElement("button");
+    confirmBtn.className = `wf-btn wf-btn--${variant} wf-btn--md`;
+    confirmBtn.textContent = confirmText;
+    footer.appendChild(cancelBtn);
+    footer.appendChild(confirmBtn);
+    box.appendChild(footer);
+    overlay.appendChild(bg);
+    overlay.appendChild(box);
+    document.body.appendChild(overlay);
+    lockScroll();
+    const close = (result) => {
+      unlockScroll();
+      overlay.remove();
+      resolve(result);
+    };
+    const onKeyDown = (e) => {
+      if (e.key === "Escape") close(false);
+    };
+    document.addEventListener("keydown", onKeyDown);
+    cancelBtn.onclick = () => {
+      document.removeEventListener("keydown", onKeyDown);
+      close(false);
+    };
+    confirmBtn.onclick = () => {
+      document.removeEventListener("keydown", onKeyDown);
+      close(true);
+    };
+    bg.onclick = () => {
+      document.removeEventListener("keydown", onKeyDown);
+      close(false);
+    };
+  });
+}
+function confirm() {
+  return (ctx) => {
+    ;
+    ctx.confirm = (message, options) => createConfirmModal(message, options ?? {});
+    return ctx;
+  };
+}
 export {
   ApiError,
   ErrorBoundary,
@@ -996,6 +1137,7 @@ export {
   RouteView,
   api,
   auth,
+  confirm,
   createApp,
   enUS,
   extendCtx,
@@ -1004,7 +1146,10 @@ export {
   jsx,
   jsxDEV,
   jsxs,
+  lockScroll,
   router,
+  trapFocus,
+  unlockScroll,
   ws,
   zhCN
 };

package/dist/client/locale/en_US.d.ts

@@ -30,9 +30,5 @@ export declare const enUS: {
         Drawer: {
             ariaLabel: string;
         };
-        InputNumber: {
-            increase: string;
-            decrease: string;
-        };
     };
 };

package/dist/client/locale/zh_CN.d.ts

@@ -30,9 +30,5 @@ export declare const zhCN: {
         Drawer: {
             ariaLabel: string;
         };
-        InputNumber: {
-            increase: string;
-            decrease: string;
-        };
     };
 };

package/dist/client/scroll-lock.d.ts

@@ -0,0 +1,5 @@
+/**
+ * weifuwu/client — ScrollLock
+ */
+export declare function lockScroll(): void;
+export declare function unlockScroll(): void;

package/dist/components/Drawer/Drawer.d.ts

@@ -1,3 +1,6 @@
+/**
+ * weifuwu/components — Drawer
+ */
 import type { Component } from '../../client/vnode.ts';
 export type DrawerPosition = 'left' | 'right';
 export interface DrawerProps {

package/dist/components/Img/Img.d.ts

@@ -0,0 +1,17 @@
+/**
+ * weifuwu/components — Img
+ *
+ * `<img>` 增强组件。支持 fallback、loading="lazy"。
+ */
+import type { Component } from '../../client/vnode.ts';
+export interface ImgProps {
+    src?: string;
+    alt?: string;
+    fallback?: string;
+    loading?: 'lazy' | 'eager';
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+    style?: Record<string, string>;
+}
+export declare const Img: Component<ImgProps>;

package/dist/components/Input/Input.d.ts

@@ -1,14 +1,13 @@
 import type { Component } from '../../client/vnode.ts';
 export interface InputProps {
     label?: string;
-    type?: 'text' | 'email' | 'password' | 'number' | 'url';
+    type?: 'text' | 'email' | 'password' | 'number' | 'url' | 'date' | 'tel' | 'time' | 'color';
     value?: string;
     placeholder?: string;
     required?: boolean;
     disabled?: boolean;
     error?: string;
     hint?: string;
-    showStepper?: boolean;
     onInput?: (e: Event) => void;
     onChange?: (e: Event) => void;
 }

package/dist/components/Modal/Modal.d.ts

@@ -1,3 +1,6 @@
+/**
+ * weifuwu/components — Modal
+ */
 import type { Component } from '../../client/vnode.ts';
 export interface ModalProps {
     open?: boolean;

package/dist/components/Popover/Popover.d.ts

@@ -0,0 +1,26 @@
+/**
+ * weifuwu/components — Popover
+ *
+ * 通用弹出层组件。触发点击后在目标元素附近弹出浮动面板。
+ * 点击面板外部关闭。
+ *
+ * 触发方式:
+ *   'click' — 点击触发元素切换显示
+ *   'hover' — 悬停触发元素显示，移出关闭
+ *
+ * 受控模式:
+ *   传入 open + onOpenChange 可外部控制显示状态
+ *   （Dropdown 使用此模式）
+ */
+import type { Component } from '../../client/vnode.ts';
+export type PopoverPosition = 'top' | 'bottom' | 'left' | 'right';
+export interface PopoverProps {
+    content?: any;
+    trigger?: 'click' | 'hover';
+    position?: PopoverPosition;
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    disabled?: boolean;
+    children?: any;
+}
+export declare const Popover: Component<PopoverProps>;

package/dist/components/Skeleton/Skeleton.d.ts

@@ -0,0 +1,21 @@
+/**
+ * weifuwu/components — Skeleton
+ *
+ * 骨架屏占位组件。纯 CSS，无交互，无状态。
+ *
+ * 用法：
+ *   <Skeleton />                    ← 单行文本
+ *   <Skeleton lines={3} />          ← 多行段落
+ *   <Skeleton variant="circle" />   ← 圆形头像
+ *   <Skeleton variant="rect" w={200} h={120} />  ← 矩形区域
+ */
+import type { Component } from '../../client/vnode.ts';
+export type SkeletonVariant = 'text' | 'circle' | 'rect';
+export interface SkeletonProps {
+    variant?: SkeletonVariant;
+    lines?: number;
+    width?: number | string;
+    height?: number | string;
+    className?: string;
+}
+export declare const Skeleton: Component<SkeletonProps>;

package/dist/components/index.d.ts

@@ -73,3 +73,9 @@ export { Tooltip } from './Tooltip/Tooltip.ts';
 export type { TooltipProps, TooltipPosition } from './Tooltip/Tooltip.ts';
 export { Drawer } from './Drawer/Drawer.ts';
 export type { DrawerProps, DrawerPosition } from './Drawer/Drawer.ts';
+export { Popover } from './Popover/Popover.ts';
+export type { PopoverProps, PopoverPosition } from './Popover/Popover.ts';
+export { Skeleton } from './Skeleton/Skeleton.ts';
+export type { SkeletonProps, SkeletonVariant } from './Skeleton/Skeleton.ts';
+export { Img } from './Img/Img.ts';
+export type { ImgProps } from './Img/Img.ts';

package/dist/components/index.js

@@ -1,4 +1,5 @@
 // src/client/vnode.ts
+var Fragment = /* @__PURE__ */ Symbol("Fragment");
 function h(type, props, ...children) {
   const p = normalizeProps(props ?? {});
   if (children.length > 0) {
@@ -37,55 +38,9 @@ var Button = (props, ctx) => {
 };
 
 // src/components/Input/Input.ts
-var Input = (props, ctx) => {
-  const { label, type = "text", value, placeholder, required, disabled, error, hint, showStepper, onInput, onChange } = props;
-  const NL = type === "number" && showStepper ? ctx?.i18n?.components?.InputNumber ?? {} : {};
-  const inputEl = type === "number" && showStepper ? h("div", { class: "wf-input-number-wrap" }, [
-    h("input", {
-      class: "wf-input",
-      type,
-      value: value ?? "",
-      placeholder,
-      required: required || void 0,
-      disabled: disabled || void 0,
-      onInput,
-      onChange
-    }),
-    h("div", { class: "wf-input-number-stepper" }, [
-      h("button", {
-        class: "wf-input-number-step",
-        "aria-label": NL.increase ?? "\u589E\u52A0",
-        disabled: disabled || void 0,
-        onClick: (e) => {
-          const input = e.currentTarget.parentElement.previousElementSibling;
-          if (input) {
-            const step = parseFloat(input.getAttribute("step") || "1");
-            const cur = parseFloat(input.value) || 0;
-            input.value = String(cur + step);
-            input.dispatchEvent(new Event("input", { bubbles: true }));
-          }
-        }
-      }, "\u25B2"),
-      h("button", {
-        class: "wf-input-number-step",
-        "aria-label": NL.decrease ?? "\u51CF\u5C11",
-        disabled: disabled || void 0,
-        onClick: (e) => {
-          const input = e.currentTarget.parentElement.previousElementSibling;
-          if (input) {
-            const step = parseFloat(input.getAttribute("step") || "1");
-            const cur = parseFloat(input.value) || 0;
-            const min = parseFloat(input.getAttribute("min") || String(-Infinity));
-            const val = cur - step;
-            if (val >= min || isNaN(min)) {
-              input.value = String(val);
-              input.dispatchEvent(new Event("input", { bubbles: true }));
-            }
-          }
-        }
-      }, "\u25BC")
-    ])
-  ]) : h("input", {
+var Input = (props) => {
+  const { label, type = "text", value, placeholder, required, disabled, error, hint, onInput, onChange } = props;
+  const inputEl = h("input", {
     class: "wf-input",
     type,
     value: value ?? "",
@@ -258,20 +213,113 @@ var Table = (props, _ctx) => {
   return h("table", { class: "wf-table" }, [thead, tbody]);
 };
 
+// src/client/scroll-lock.ts
+var lockedCount = 0;
+var originalOverflow = "";
+var originalPosition = "";
+var originalTop = "";
+var originalWidth = "";
+var scrollY = 0;
+function canLock() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function lockScroll() {
+  lockedCount++;
+  if (lockedCount > 1) return;
+  if (!canLock()) return;
+  scrollY = window.scrollY;
+  const body = document.body;
+  originalOverflow = body.style.overflow;
+  originalPosition = body.style.position;
+  originalTop = body.style.top;
+  originalWidth = body.style.width;
+  body.style.overflow = "hidden";
+  const isIOS = /iPhone|iPad|iPod/.test(navigator.platform) || /Mac/.test(navigator.platform) && "ontouchend" in document;
+  if (isIOS) {
+    body.style.position = "fixed";
+    body.style.top = `-${scrollY}px`;
+    body.style.width = "100%";
+  }
+}
+function unlockScroll() {
+  lockedCount--;
+  if (lockedCount > 0) return;
+  if (!canLock()) return;
+  const body = document.body;
+  body.style.overflow = originalOverflow;
+  body.style.position = originalPosition;
+  body.style.top = originalTop;
+  body.style.width = originalWidth;
+  if (scrollY > 0) window.scrollTo(0, scrollY);
+}
+
+// src/client/focus-trap.ts
+var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), textarea:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+function trapFocus(container) {
+  const focusable = container.querySelectorAll(FOCUSABLE);
+  if (focusable.length === 0) return () => {
+  };
+  const first = focusable[0];
+  const last = focusable[focusable.length - 1];
+  const handler = (e) => {
+    if (e.key !== "Tab") return;
+    if (e.shiftKey && document.activeElement === first) {
+      e.preventDefault();
+      last.focus();
+    } else if (!e.shiftKey && document.activeElement === last) {
+      e.preventDefault();
+      first.focus();
+    }
+  };
+  const prevFocused = document.activeElement;
+  first.focus();
+  container.addEventListener("keydown", handler);
+  return () => {
+    container.removeEventListener("keydown", handler);
+    prevFocused?.focus();
+  };
+}
+
 // src/components/Modal/Modal.ts
 var Modal = (props, ctx) => {
   const { open, title, onClose, children, footer } = props;
-  if (!open) return null;
+  const $ = ctx.ui.$;
+  if (!ctx.ui.ready) {
+    $.exiting = false;
+    $.prevOpen = open;
+  }
+  if ($.prevOpen !== open) {
+    $.prevOpen = open;
+    if (open && $.exiting) $.exiting = false;
+  }
+  const startClose = () => {
+    $.exiting = true;
+  };
+  const onExitEnd = () => {
+    $.exiting = false;
+    onClose?.();
+  };
+  if (!open && !$.exiting) return null;
+  const isClosing = $.exiting;
   const handleKeyDown = (e) => {
-    if (e.key === "Escape" && onClose) onClose();
+    if (e.key === "Escape" && !isClosing) startClose();
+  };
+  const modalRef = (el) => {
+    if (!el) return;
+    lockScroll();
+    const cleanupFocus = trapFocus(el);
+    return () => {
+      unlockScroll();
+      cleanupFocus();
+    };
   };
   const overlay = h("div", {
     class: "wf-modal-overlay",
-    onClick: onClose
+    onClick: isClosing ? void 0 : startClose
   });
   const closeBtn = h("button", {
     class: "wf-modal-close",
-    onClick: onClose,
+    onClick: isClosing ? void 0 : startClose,
     type: "button"
   }, "\u2715");
   const titleEl = title ? h("div", { class: "wf-modal-header" }, [title, closeBtn]) : null;
@@ -282,12 +330,15 @@ var Modal = (props, ctx) => {
     onClick: (e) => e.stopPropagation()
   }, [titleEl, bodyEl, footerEl].filter(Boolean));
   const ML = ctx?.i18n?.components?.Modal ?? {};
+  const cls = isClosing ? "wf-modal wf-modal--exit" : "wf-modal wf-modal--enter";
   return h("div", {
-    class: "wf-modal",
+    class: cls,
     role: "dialog",
     "aria-modal": "true",
     "aria-label": title ?? (ML.ariaLabel ?? "\u5F39\u7A97"),
-    onKeyDown: handleKeyDown
+    onKeyDown: handleKeyDown,
+    onAnimationEnd: isClosing ? onExitEnd : void 0,
+    ref: modalRef
   }, [overlay, content]);
 };
 
@@ -819,17 +870,43 @@ var Tooltip = (props, ctx) => {
 // src/components/Drawer/Drawer.ts
 var Drawer = (props, ctx) => {
   const { open, title, position = "right", onClose, children, footer } = props;
-  if (!open) return null;
+  const $ = ctx.ui.$;
+  if (!ctx.ui.ready) {
+    $.exiting = false;
+    $.prevOpen = open;
+  }
+  if ($.prevOpen !== open) {
+    $.prevOpen = open;
+    if (open && $.exiting) $.exiting = false;
+  }
+  const startClose = () => {
+    $.exiting = true;
+  };
+  const onExitEnd = () => {
+    $.exiting = false;
+    onClose?.();
+  };
+  if (!open && !$.exiting) return null;
+  const isClosing = $.exiting;
   const handleKeyDown = (e) => {
-    if (e.key === "Escape" && onClose) onClose();
+    if (e.key === "Escape" && !isClosing) startClose();
+  };
+  const drawerRef = (el) => {
+    if (!el) return;
+    lockScroll();
+    const cleanupFocus = trapFocus(el);
+    return () => {
+      unlockScroll();
+      cleanupFocus();
+    };
   };
   const overlay = h("div", {
     class: "wf-drawer-overlay",
-    onClick: onClose
+    onClick: isClosing ? void 0 : startClose
   });
   const closeBtn = h("button", {
     class: "wf-drawer-close",
-    onClick: onClose,
+    onClick: isClosing ? void 0 : startClose,
     type: "button",
     "aria-label": "\u5173\u95ED"
   }, "\u2715");
@@ -838,17 +915,114 @@ var Drawer = (props, ctx) => {
   const footerEl = footer ? h("div", { class: "wf-drawer-footer" }, footer) : null;
   const panel = h("div", {
     class: `wf-drawer-panel wf-drawer-panel--${position}`,
-    onClick: (e) => e.stopPropagation()
+    onClick: (e) => e.stopPropagation(),
+    onAnimationEnd: isClosing ? onExitEnd : void 0
   }, [titleEl, bodyEl, footerEl].filter(Boolean));
   const DL = ctx?.i18n?.components?.Drawer ?? {};
+  const cls = isClosing ? `wf-drawer wf-drawer--${position} wf-drawer--exit` : `wf-drawer wf-drawer--${position} wf-drawer--enter`;
   return h("div", {
-    class: `wf-drawer wf-drawer--${position}`,
+    class: cls,
     role: "dialog",
     "aria-modal": "true",
     "aria-label": title ?? (DL.ariaLabel ?? "\u4FA7\u8FB9\u9762\u677F"),
-    onKeyDown: handleKeyDown
+    onKeyDown: handleKeyDown,
+    ref: drawerRef
   }, [overlay, panel]);
 };
+
+// src/components/Popover/Popover.ts
+var Popover = (props, ctx) => {
+  const {
+    content,
+    trigger = "click",
+    position = "bottom",
+    open,
+    onOpenChange,
+    disabled,
+    children
+  } = props;
+  const $ = ctx.ui.$;
+  if (!ctx.ui.ready) {
+    $.show = false;
+  }
+  const isOpen = open !== void 0 ? open : $.show;
+  const setOpen = (v) => {
+    if (open === void 0) $.show = v;
+    onOpenChange?.(v);
+  };
+  const onClick = trigger === "click" && !disabled ? () => setOpen(!isOpen) : void 0;
+  const hoverProps = {};
+  if (trigger === "hover" && !disabled) {
+    hoverProps.onMouseEnter = () => setOpen(true);
+    hoverProps.onMouseLeave = () => setOpen(false);
+    hoverProps.onFocus = () => setOpen(true);
+    hoverProps.onBlur = () => setOpen(false);
+  }
+  const overlay = isOpen ? h("div", {
+    class: "wf-popover-overlay",
+    onMouseDown: () => setOpen(false)
+  }) : null;
+  const panel = isOpen ? h("div", {
+    class: `wf-popover wf-popover--${position}`,
+    role: "dialog",
+    "aria-modal": "true",
+    "aria-label": "\u5F39\u51FA\u9762\u677F",
+    onMouseDown: (e) => e.stopPropagation()
+  }, [
+    h("div", { class: "wf-popover-arrow" }),
+    h("div", { class: "wf-popover-content" }, content)
+  ]) : null;
+  return h("div", {
+    class: `wf-popover-wrap${isOpen ? " wf-popover-wrap--open" : ""}`,
+    ...hoverProps
+  }, [
+    h("div", { class: "wf-popover-trigger", onClick }, children),
+    overlay,
+    panel
+  ].filter(Boolean));
+};
+
+// src/components/Skeleton/Skeleton.ts
+var Skeleton = (props) => {
+  const { variant = "text", lines = 1, width, height, className } = props;
+  const style = {};
+  if (width !== void 0) style.width = typeof width === "number" ? `${width}px` : width;
+  if (height !== void 0) style.height = typeof height === "number" ? `${height}px` : height;
+  const cls = [
+    "wf-skeleton",
+    `wf-skeleton--${variant}`,
+    className
+  ].filter(Boolean).join(" ");
+  if (lines <= 1) {
+    return h("div", { class: cls, style: Object.keys(style).length ? style : void 0 });
+  }
+  const items = Array.from({ length: lines }, (_, i) => {
+    const itemCls = i === lines - 1 && lines > 1 ? `${cls} wf-skeleton--short` : cls;
+    return h("div", { class: itemCls, style: Object.keys(style).length ? style : void 0 });
+  });
+  return h(Fragment, null, items);
+};
+
+// src/components/Img/Img.ts
+var Img = (props) => {
+  const { src, alt = "", fallback, loading, width, height, className, style } = props;
+  const imgProps = {
+    class: ["wf-image", className].filter(Boolean).join(" "),
+    src: src ?? fallback ?? "",
+    alt,
+    loading: loading ?? "lazy"
+  };
+  if (width !== void 0) imgProps.width = width;
+  if (height !== void 0) imgProps.height = height;
+  if (style) imgProps.style = style;
+  if (fallback) {
+    imgProps.onError = (e) => {
+      const el = e.currentTarget;
+      if (el.src !== fallback) el.src = fallback;
+    };
+  }
+  return h("img", imgProps);
+};
 export {
   Accordion,
   Alert,
@@ -865,15 +1039,18 @@ export {
   Field,
   FileUpload,
   Form,
+  Img,
   Input,
   Loading,
   Modal,
   PageHeader,
   Pagination,
+  Popover,
   ProgressBar,
   RadioGroup,
   SearchInput,
   Select,
+  Skeleton,
   Slider,
   StatCard,
   Steps,

package/dist/components/style.css

@@ -519,6 +519,24 @@
   z-index: var(--wf-cover-z);
 }
 
+.wf-modal--enter {
+  animation: wf-modal-fadein 0.2s ease-out;
+}
+
+.wf-modal--exit {
+  animation: wf-modal-fadeout 0.2s ease-out forwards;
+}
+
+@keyframes wf-modal-fadein {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+@keyframes wf-modal-fadeout {
+  from { opacity: 1; }
+  to   { opacity: 0; }
+}
+
 .wf-modal-overlay {
   position: fixed;
   inset: 0;
@@ -1595,8 +1613,8 @@
 }
 
 @keyframes wf-tooltip-fadein {
-  from { opacity: 0; transform: translateY(2px); }
-  to   { opacity: 1; transform: translateY(0); }
+  from { opacity: 0; }
+  to   { opacity: 1; }
 }
 
 .wf-tooltip-content {
@@ -1653,6 +1671,7 @@
   top: 50%;
   transform: translateY(-50%);
   padding-right: 4px;
+  flex-direction: row;
 }
 
 .wf-tooltip--left .wf-tooltip-arrow {
@@ -1666,6 +1685,7 @@
   top: 50%;
   transform: translateY(-50%);
   padding-left: 4px;
+  flex-direction: row;
 }
 
 .wf-tooltip--right .wf-tooltip-arrow {
@@ -1694,14 +1714,26 @@
   position: absolute;
   inset: 0;
   background: rgba(0, 0, 0, 0.4);
+}
+
+.wf-drawer--enter .wf-drawer-overlay {
   animation: wf-drawer-overlay-fadein 0.2s ease-out;
 }
 
+.wf-drawer--exit .wf-drawer-overlay {
+  animation: wf-drawer-overlay-fadeout 0.2s ease-out forwards;
+}
+
 @keyframes wf-drawer-overlay-fadein {
   from { opacity: 0; }
   to   { opacity: 1; }
 }
 
+@keyframes wf-drawer-overlay-fadeout {
+  from { opacity: 1; }
+  to   { opacity: 0; }
+}
+
 .wf-drawer-panel {
   position: relative;
   display: flex;
@@ -1711,17 +1743,32 @@
   height: 100%;
   background: var(--wf-color-bg);
   box-shadow: var(--wf-shadow-lg, 0 4px 24px rgba(0, 0, 0, 0.12));
+}
+
+.wf-drawer--enter .wf-drawer-panel {
   animation: wf-drawer-slidein 0.25s ease-out;
 }
 
-.wf-drawer-panel--right {
+.wf-drawer--enter .wf-drawer-panel--right {
   animation-name: wf-drawer-slidein-right;
 }
 
-.wf-drawer-panel--left {
+.wf-drawer--enter .wf-drawer-panel--left {
   animation-name: wf-drawer-slidein-left;
 }
 
+.wf-drawer--exit .wf-drawer-panel {
+  animation: wf-drawer-slideout 0.2s ease-out forwards;
+}
+
+.wf-drawer--exit .wf-drawer-panel--right {
+  animation-name: wf-drawer-slideout-right;
+}
+
+.wf-drawer--exit .wf-drawer-panel--left {
+  animation-name: wf-drawer-slideout-left;
+}
+
 @keyframes wf-drawer-slidein-right {
   from { transform: translateX(100%); }
   to   { transform: translateX(0); }
@@ -1732,6 +1779,16 @@
   to   { transform: translateX(0); }
 }
 
+@keyframes wf-drawer-slideout-right {
+  from { transform: translateX(0); }
+  to   { transform: translateX(100%); }
+}
+
+@keyframes wf-drawer-slideout-left {
+  from { transform: translateX(0); }
+  to   { transform: translateX(-100%); }
+}
+
 .wf-drawer-header {
   display: flex;
   align-items: center;
@@ -1777,3 +1834,172 @@
   border-top: var(--wf-border-width, 1px) solid var(--wf-color-border);
 }
 
+/* weifuwu/components — Popover */
+
+.wf-popover-wrap {
+  position: relative;
+  display: inline-flex;
+}
+
+.wf-popover-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 998;
+}
+
+.wf-popover {
+  position: absolute;
+  z-index: 999;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  animation: wf-popover-fadein 0.15s ease-out;
+}
+
+@keyframes wf-popover-fadein {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+
+.wf-popover-content {
+  font-family: var(--wf-font-sans);
+  font-size: var(--wf-font-size-sm);
+  color: var(--wf-color-text);
+  background: var(--wf-color-bg);
+  border: 1px solid var(--wf-color-border);
+  border-radius: var(--wf-radius);
+  box-shadow: 0 4px 12px rgba(0,0,0,0.1);
+  padding: var(--wf-space-sm);
+  min-width: 120px;
+  max-width: 320px;
+  line-height: var(--wf-line-height-normal);
+}
+
+.wf-popover-arrow {
+  width: 8px;
+  height: 8px;
+  background: var(--wf-color-bg);
+  border: 1px solid var(--wf-color-border);
+  transform: rotate(45deg);
+  border-radius: 1px;
+}
+
+.wf-popover-arrow {
+  border-bottom: none;
+  border-right: none;
+}
+
+/* 位置: top */
+.wf-popover--top {
+  bottom: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  padding-bottom: 6px;
+}
+
+.wf-popover--top .wf-popover-arrow {
+  order: 1;
+  margin-top: -4px;
+  border: none;
+  border-top: 1px solid var(--wf-color-border);
+  border-left: 1px solid var(--wf-color-border);
+}
+
+/* 位置: bottom */
+.wf-popover--bottom {
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  padding-top: 6px;
+}
+
+.wf-popover--bottom .wf-popover-arrow {
+  order: -1;
+  margin-bottom: -4px;
+  border: none;
+  border-bottom: 1px solid var(--wf-color-border);
+  border-right: 1px solid var(--wf-color-border);
+}
+
+/* 位置: left */
+.wf-popover--left {
+  right: 100%;
+  top: 50%;
+  transform: translateY(-50%);
+  padding-right: 6px;
+  flex-direction: row;
+}
+
+.wf-popover--left .wf-popover-arrow {
+  order: 1;
+  margin-left: -4px;
+  border: none;
+  border-left: 1px solid var(--wf-color-border);
+  border-bottom: 1px solid var(--wf-color-border);
+}
+
+/* 位置: right */
+.wf-popover--right {
+  left: 100%;
+  top: 50%;
+  transform: translateY(-50%);
+  padding-left: 6px;
+  flex-direction: row;
+}
+
+.wf-popover--right .wf-popover-arrow {
+  order: -1;
+  margin-right: -4px;
+  border: none;
+  border-right: 1px solid var(--wf-color-border);
+  border-top: 1px solid var(--wf-color-border);
+}
+
+/* weifuwu/components — Skeleton */
+
+.wf-skeleton {
+  display: inline-block;
+  height: 1em;
+  border-radius: var(--wf-radius-sm, 4px);
+  background: linear-gradient(
+    90deg,
+    var(--wf-color-border, #e5e7eb) 25%,
+    var(--wf-color-bg-hover, #f3f4f6) 50%,
+    var(--wf-color-border, #e5e7eb) 75%
+  );
+  background-size: 200% 100%;
+  animation: wf-skeleton-shimmer 1.5s ease-in-out infinite;
+  vertical-align: middle;
+}
+
+@keyframes wf-skeleton-shimmer {
+  0%   { background-position: 200% 0; }
+  100% { background-position: -200% 0; }
+}
+
+/* 变体 */
+
+.wf-skeleton--text {
+  width: 100%;
+  min-width: 60px;
+}
+
+.wf-skeleton--circle {
+  border-radius: 50%;
+  width: 40px;
+  height: 40px;
+  min-width: unset;
+}
+
+.wf-skeleton--rect {
+  border-radius: var(--wf-radius, 8px);
+  width: 100%;
+  height: 120px;
+}
+
+/* 多行：最后一行缩短 */
+
+.wf-skeleton--short {
+  width: 60%;
+}
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {