npm - weifuwu - Versions diffs - 0.51.1 → 0.53.0 - Mend

weifuwu 0.51.1 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md +107 -16
package/dist/client/index.js +249 -76
package/dist/client/render.d.ts +7 -1
package/dist/client/vnode.d.ts +6 -2
package/dist/components/index.js +56 -19
package/dist/components/style.css +24 -0
package/dist/layout/weifuwu-layout.css +24 -0
package/package.json +2 -2

package/README.md CHANGED Viewed

@@ -82,7 +82,7 @@ createApp()
   <!-- 组件样式（可选，如只用 weifuwu/client 则不需要） -->
   <link
     rel="stylesheet"
-    href="https://unpkg.com/weifuwu@0.51.0/dist/components/style.css"
+    href="https://unpkg.com/weifuwu@latest/dist/components/style.css"
   />
 </head>
 <body>
@@ -92,8 +92,8 @@ createApp()
   <script type="importmap">
     {
       "imports": {
-        "weifuwu/client": "https://unpkg.com/weifuwu@0.51.0/dist/client/index.js",
-        "weifuwu/components": "https://unpkg.com/weifuwu@0.51.0/dist/components/index.js"
+        "weifuwu/client": "https://unpkg.com/weifuwu@latest/dist/client/index.js",
+        "weifuwu/components": "https://unpkg.com/weifuwu@latest/dist/components/index.js"
       }
     }
   </script>
@@ -137,12 +137,11 @@ createApp()
 | 资源 | CDN 地址 | 说明 |
 |------|---------|------|
-| `weifuwu/client` | `https://unpkg.com/weifuwu@0.51.0/dist/client/index.js` | 客户端核心（createApp, h, 路由, 状态管理等） |
-| `weifuwu/components` | `https://unpkg.com/weifuwu@0.51.0/dist/components/index.js` | 41 个 UI 组件（Button, Card, Table, Modal 等） |
-| 组件样式 | `https://unpkg.com/weifuwu@0.51.0/dist/components/style.css` | 组件 CSS + 72 个主题 Token + 35 个布局原语 |
-| 独立布局系统 | `https://unpkg.com/weifuwu@0.51.0/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
+| `weifuwu/client` | `https://unpkg.com/weifuwu@latest/dist/client/index.js` | 客户端核心（createApp, h, 路由, 状态管理等） |
+| `weifuwu/components` | `https://unpkg.com/weifuwu@latest/dist/components/index.js` | 41 个 UI 组件（Button, Card, Table, Modal 等） |
+| 组件样式 | `https://unpkg.com/weifuwu@latest/dist/components/style.css` | 组件 CSS + 72 个主题 Token + 35 个布局原语 |
+| 独立布局系统 | `https://unpkg.com/weifuwu@latest/dist/layout/weifuwu-layout.css` | 仅 CSS 布局，不依赖 JS |
-> 提示：将 `@0.51.0` 替换为 `@latest` 始终使用最新版，或固定版本避免意外变更。
 ---
@@ -898,6 +897,8 @@ h('div', { class: 'x' }, child1, child2)
 | `ctx.ui.dirty()` | 主动调用 | 微任务批量（异步） | 当前/指定 | **绕过 Proxy 后手动标记** |
 | `ctx.ui.render()` | 主动调用 | 立即同步 | 当前/指定 | **需要立即拿到最新 DOM** — DOM 测量、动画触发 |
 | `ctx.ui.render(['id'])` | 主动调用 | 立即同步 | 指定组件 | **跨组件精准刷新** — 全局事件、Portal 远程控制 |
+| `ctx.ui.useMedia()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **响应式媒体查询** — 断点变化时自动 dirty |
+| `ctx.ui.useBreakpoint()` | 注册监听 | 浏览器事件驱动 | 当前组件 | **命名断点** — mobile/tablet/desktop 自动 dirty |
 `render()` 和 `dirty()` 无参 = 当前组件，传参 = 指定组件列表。三套 API 同一 scope 机制。
@@ -945,6 +946,79 @@ const FormPage: Component = (_init, ctx) => {
 - 不需要触发渲染的内部缓存（用闭包变量 `let`）
 - 简单组件只有一两个状态变量（闭包变量 + `render()` 更轻量）
+### 响应式自适应组件
+#### `ctx.ui.useMedia(query, callback)` — 响应式媒体查询
+注册媒体查询监听，值变化时自动调用 callback（callback 内赋值 `$` 触发 dirty）：
+```tsx
+const Card = (_init, ctx) => {
+  const $ = ctx.ui.$()
+  $.isMobile = false
+  // 立即回调一次（取当前值），之后变化时自动重新回调
+  ctx.ui.useMedia('(max-width: 640px)', (v) => { $.isMobile = v })
+  return (props) => (
+    <div class={$.isMobile ? 'wf-stack' : 'wf-row'}>
+      {!$.isMobile && <Sidebar />}
+      <Content />
+    </div>
+  )
+}
+```
+`callback` 在 mount 时立即执行一次，之后断点变化时再次执行。赋值给 `$` 的属性自动触发渲染。
+#### `ctx.ui.useBreakpoint(callback)` — 命名断点
+预设三个断点名称：`mobile`（<640px）、`tablet`（640-1023px）、`desktop`（≥1024px）：
+```tsx
+const Layout = (_init, ctx) => {
+  const $ = ctx.ui.$()
+  ctx.ui.useBreakpoint((vp) => { $.vp = vp })
+  return (props) =>
+    <div class={`sidebar-${$.vp}`}>
+      {$.vp === 'mobile' ? <BottomNav /> : <SideNav />}
+      {$.vp === 'mobile' ? <MobileContent /> : <Content />}
+    </div>
+}
+```
+也支持自定义断点：
+```tsx
+ctx.ui.useBreakpoint(
+  { narrow: '(max-width: 480px)', wide: '(min-width: 1200px)' },
+  (vp) => { $.size = vp },
+)
+```
+#### CSS 层响应式（不碰 JS）
+配合 `weifuwu/layout` 的断点变体，纯 CSS 实现布局方向切换：
+```html
+<!-- 小屏堆叠，桌面并排 -->
+<div class="wf-stack wf-stack@md"></div>
+<!-- 小屏隐藏侧栏 -->
+<aside class="wf-hidden wf-block@md"></aside>
+```
+可用断点变体：
+| 原语 | 变体 | 效果 |
+|------|------|------|
+| `wf-stack` | `@sm` `@md` `@lg` | 断点以上改为横向排列 |
+| `wf-row` | `@sm` `@md` `@lg` | 断点以上保持横向 |
+| `wf-hidden` | `@sm` `@md` `@lg` | 断点以上隐藏 |
+| `wf-block` | `@sm` `@md` `@lg` | 断点以上显示 |
+断点尺寸：`--wf-bp-sm: 640px` / `--wf-bp-md: 768px` / `--wf-bp-lg: 1024px` / `--wf-bp-xl: 1280px`
 ### `ctx.ui.dirty()` — 异步标记脏
 异步版本，无参 = 当前组件，传参 = 指定组件列表。多次调用合并为一次微任务渲染。`$` 内部就是调 `dirty()`。
@@ -1004,8 +1078,14 @@ ctx.ui.dirty(['stats'])  // 批处理合并
 **性能说明**：
 - `$.x = val` 和 `dirty()` 都是微任务批量合并
-- `render()` 每次调用都触发一次完整 diff/patch
-- 三个入口同一套 scope 机制，不想要的渲染不触发
+- `render()` 从 dirty 组件**向下**遍历（scope render），兄弟组件不遍历
+- **三态 skip 自动优化**：组件重新渲染时，框架自动检查三个维度：
+  - **props**（含 children 元素级比较）——值没变则不渲染
+  - **`$` 状态**——没被 dirty 标记则不渲染
+  - **ctx 版本**——ctx 没变化则不渲染
+  三个条件全部满足时跳过整个子树（零 `_render` 调用、零 `patchValue` 遍历）
+- **lastIndex keyed diff**：列表 diff 采用正向 lastIndex 算法（React 同款），顺序不变时零 `insertBefore`。对比传统的逆序循环全量移动，DOM 修改从 O(N) 降到 O(0)。
+- 示例：DemoButton 点击一次，DOM 修改从 34 次降到 **1 次**（仅变更文本节点的 `textContent`）
 ### 实践建议
@@ -1038,6 +1118,17 @@ const OrderPage = (_init, ctx) => {
 同一个组件内可以按变量混用两种模式：需要渲染的用 `$`，不需要的用 `let`。
+### VDOM diff 优化机制
+weifuwu 的 VDOM 在每次 render 时自动执行**三态 skip 判定**，减少不必要的组件渲染和 DOM 操作：
+```
+canSkip = (props 没变) AND ($ 没脏) AND (ctx 版本一致)
+          ↑ 值级浅比较    ↑ VNode dirty 标记  ↑ 全局版本号
+```
+三个维度各自独立判断，AND 合并。任何一个维度说
 ---
 ## 条件与列表
@@ -1766,10 +1857,10 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 | 类别 | 原语 | 效果 |
 |------|------|------|
-| **排列** | `wf-stack` | 纵向 flex + gap |
-| | `wf-stack-reverse` | 纵向反向 |
-| | `wf-row` | 横向 flex + wrap + gap |
-| | `wf-row-reverse` | 横向反向 |
+| **排列** | `wf-stack` `wf-stack@sm/md/lg` | 纵向 flex + gap（断点变体→横向） |
+| | `wf-stack-reverse` `@sm/md/lg` | 纵向反向 |
+| | `wf-row` `wf-row@sm/md/lg` | 横向 flex + wrap + gap |
+| | `wf-row-reverse` `@sm/md/lg` | 横向反向 |
 | | `wf-nowrap` | flex-wrap: nowrap |
 | | `wf-cluster` | 换行居中簇 |
 | **分布** | `wf-split` | justify-content: space-between |
@@ -1794,8 +1885,8 @@ app.get('/layout.css', (req, ctx) => ctx.ui.css('weifuwu/layout'))
 | | `wf-container` | max-width + margin: auto |
 | | `wf-scroll` | overflow: auto |
 | | `wf-clip` | overflow: hidden |
-| **显隐** | `wf-hidden` | display: none |
-| | `wf-block` | display: block |
+| **显隐** | `wf-hidden` `wf-hidden@sm/md/lg` | display: none |
+| | `wf-block` `wf-block@sm/md/lg` | display: block |
 | | `wf-inline` | display: inline |
 | | `wf-inline-block` | display: inline-block |
 | | `wf-contents` | display: contents |

package/dist/client/index.js CHANGED Viewed

@@ -32,7 +32,8 @@ function createPortal(children, portalKey) {
   return {
     type: Portal,
     props: { children, portalKey },
-    key: portalKey ?? void 0
+    key: portalKey ?? void 0,
+    _placement: "remote"
   };
 }
@@ -45,16 +46,20 @@ function render(input, ctx) {
   return renderValue(input, ctx);
 }
 function renderValue(v, ctx) {
-  if (v == null || typeof v === "boolean") return document.createTextNode("");
+  if (v == null || typeof v === "boolean") return null;
   if (typeof v === "string" || typeof v === "number") return document.createTextNode(String(v));
   if (Array.isArray(v)) return renderArray(v, ctx);
   const vnode = v;
   if (vnode.type === Portal) {
-    return renderPortal(vnode, ctx);
+    renderPortal(vnode, ctx);
+    return null;
   }
   if (vnode.type === Fragment) {
     const frag = document.createDocumentFragment();
-    forEach(vnode.props?.children, (child) => frag.appendChild(renderValue(child, ctx)));
+    forEach(vnode.props?.children, (child) => {
+      const node = renderValue(child, ctx);
+      if (node != null) frag.appendChild(node);
+    });
     return frag;
   }
   if (typeof vnode.type === "function") {
@@ -79,6 +84,7 @@ function renderValue(v, ctx) {
     const flatChildren = flattenChildren(vnode.props?.children);
     for (const child of flatChildren) {
       const childNode = renderValue(child, ctx);
+      if (childNode == null) continue;
       el.appendChild(childNode);
       if (child && typeof child === "object" && typeof child.type === "function") {
         const childVNode = child;
@@ -107,6 +113,7 @@ function renderComponent(Comp, props, vnode, ctx) {
   childCtx.ui = Object.create(ctx.ui);
   childCtx.ui._selfId = vnode._id;
   childCtx.ui._selfVNode = vnode;
+  vnode._ctxVersion = childCtx.ui._ctxVersion ?? 0;
   let childVNode;
   try {
     childVNode = Comp(props, childCtx);
@@ -129,7 +136,7 @@ function renderComponent(Comp, props, vnode, ctx) {
   }
   if (childVNode == null) {
     vnode._child = null;
-    return document.createTextNode("");
+    return null;
   }
   vnode._child = childVNode;
   const domNode = renderValue(childVNode, childCtx);
@@ -141,7 +148,10 @@ function renderComponent(Comp, props, vnode, ctx) {
 }
 function renderArray(arr, ctx) {
   const frag = document.createDocumentFragment();
-  for (const item of arr) frag.appendChild(renderValue(item, ctx));
+  for (const item of arr) {
+    const node = renderValue(item, ctx);
+    if (node != null) frag.appendChild(node);
+  }
   return frag;
 }
 function ensurePortalContainer() {
@@ -159,25 +169,26 @@ function renderPortal(vnode, ctx) {
   const sub = document.createElement("div");
   sub.style.pointerEvents = "auto";
   container.appendChild(sub);
-  vnode._portalEl = sub;
+  vnode._remoteEl = sub;
   const children = normalize(vnode.props?.children);
   vnode._child = children;
   for (const child of children) {
-    sub.appendChild(renderValue(child, ctx));
+    const node = renderValue(child, ctx);
+    if (node != null) sub.appendChild(node);
   }
-  const placeholder = document.createTextNode("");
-  vnode.el = placeholder;
-  return placeholder;
 }
-function patchPortal(_parent, oldNode, oldV, newV, ctx) {
-  const sub = oldV._portalEl;
-  newV._portalEl = sub;
-  if (!sub) return renderPortal(newV, ctx);
+function patchPortal(oldV, newV, ctx) {
+  const sub = oldV?._remoteEl;
+  newV._remoteEl = sub;
+  if (!sub) {
+    renderPortal(newV, ctx);
+    return;
+  }
   const newChildren = normalize(newV.props?.children);
   const oldChildren = oldV._child || [];
   newV._child = newChildren;
-  patchSimpleChildren(sub, oldChildren, newChildren, ctx);
-  return oldNode ?? document.createTextNode("");
+  ensureKeys(oldChildren, newChildren);
+  patchKeyedChildren(sub, oldChildren, newChildren, ctx);
 }
 function forEach(children, fn) {
   if (children == null) return;
@@ -225,6 +236,7 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
   if (oldInput == null) {
     if (newInput == null) return null;
     const node = renderValue(newInput, ctx);
+    if (node == null) return null;
     if (oldNode && oldNode.parentNode) {
       oldNode.parentNode.insertBefore(node, oldNode);
     } else {
@@ -236,6 +248,8 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
     if (oldNode) {
       callRefCleanup(oldInput);
       oldNode.remove();
+    } else {
+      callRefCleanup(oldInput);
     }
     return null;
   }
@@ -244,6 +258,7 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
   if (oldType !== newType) {
     callRefCleanup(oldInput);
     const node = renderValue(newInput, ctx);
+    if (node == null) return null;
     if (oldNode?.parentNode) {
       oldNode.parentNode.replaceChild(node, oldNode);
     }
@@ -270,6 +285,13 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
     childCtx.ui = Object.create(ctx.ui);
     childCtx.ui._selfId = newV._id;
     childCtx.ui._selfVNode = newV;
+    newV._ctxVersion = oldV._ctxVersion ?? childCtx.ui._ctxVersion ?? 0;
+    if (oldV._render && componentPropsEqual(oldV.props, newV.props) && !childCtx.ui._dirtySet?.has(oldV._id) && newV._ctxVersion === childCtx.ui._ctxVersion) {
+      newV._child = oldV._child;
+      return oldNode;
+    }
+    ;
+    childCtx.ui._dirtySet?.delete(oldV._id);
     let childNew;
     try {
       if (typeof newV._render === "function") {
@@ -293,7 +315,9 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
     }
     const _prevChild = oldV._child;
     newV._child = childNew;
-    return patchValue(parent, oldNode, _prevChild, childNew, childCtx);
+    const returnedNode = patchValue(parent, oldNode, _prevChild, childNew, childCtx);
+    if (!returnedNode) newV._refNode = null;
+    return returnedNode;
   }
   if (newV.type === Fragment) {
     patchChildren(parent, oldV, newV, ctx);
@@ -312,17 +336,20 @@ function patchValue(parent, oldNode, oldInput, newInput, ctx) {
     } else if (oldNode) {
       callRefCleanup(oldInput);
       const node = renderValue(newInput, ctx);
+      if (node == null) return null;
       oldNode.parentNode?.replaceChild(node, oldNode);
       return node;
     }
     return oldNode;
   }
   if (newV.type === Portal) {
-    return patchPortal(parent, oldNode, oldV, newV, ctx);
+    patchPortal(oldV, newV, ctx);
+    return null;
   }
   if (Array.isArray(newInput)) {
     const oldArr = Array.isArray(oldInput) ? oldInput : [];
-    patchSimpleChildren(parent, oldArr, newInput, ctx);
+    ensureKeys(oldArr, newInput);
+    patchKeyedChildren(parent, oldArr, newInput, ctx);
     return oldNode;
   }
   return oldNode;
@@ -396,15 +423,24 @@ function getKey(input) {
   if (input == null || typeof input !== "object") return void 0;
   return input.key;
 }
+function ensureKeys(oldChildren, newChildren) {
+  const hasKey = newChildren.some((c) => c && typeof c === "object" && c.key !== void 0);
+  if (!hasKey) {
+    for (let i = 0; i < newChildren.length; i++) {
+      const c = newChildren[i];
+      if (c && typeof c === "object") c.key = i;
+    }
+    for (let i = 0; i < oldChildren.length; i++) {
+      const c = oldChildren[i];
+      if (c && typeof c === "object") c.key = i;
+    }
+  }
+}
 function patchChildren(parent, oldVNode, newVNode, ctx) {
   const oldChildren = normalize(oldVNode.props?.children);
   const newChildren = normalize(newVNode.props?.children);
-  const hasKey = newChildren.some((c) => getKey(c) !== void 0);
-  if (hasKey) {
-    patchKeyedChildren(parent, oldChildren, newChildren, ctx);
-  } else {
-    patchSimpleChildren(parent, oldChildren, newChildren, ctx);
-  }
+  ensureKeys(oldChildren, newChildren);
+  patchKeyedChildren(parent, oldChildren, newChildren, ctx);
 }
 function normalize(children) {
   if (children == null) return [];
@@ -419,38 +455,56 @@ 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();
+function patchKeyedChildren(parent, oldChildren, newChildren, ctx) {
+  const allUnkeyed = !newChildren.some((c) => c && typeof c === "object" && c.key !== void 0);
+  if (allUnkeyed) {
+    const len = Math.max(oldChildren.length, newChildren.length);
+    for (let i = 0; i < len; i++) {
+      const oldC = i < oldChildren.length ? oldChildren[i] : null;
+      const newC = i < newChildren.length ? newChildren[i] : null;
+      if (newC == null) {
+        if (oldC != null) {
+          callRefCleanup(oldC);
+          const node = parent.childNodes[i];
+          if (node) node.remove();
+        }
+      } else if (oldC == null) {
+        const node = renderValue(newC, ctx);
+        if (node != null) parent.appendChild(node);
+      } else {
+        const oldNode = parent.childNodes[i] || null;
+        patchValue(parent, oldNode, oldC, newC, ctx);
+      }
     }
+    return;
   }
-  const max = Math.max(oldChildren.length, newChildren.length);
-  const oldNodes = [];
-  for (let i = 0; i < max; i++) {
-    oldNodes.push(parent.childNodes[i] || null);
-  }
-  for (let i = 0; i < max; i++) {
-    const oldChild = oldChildren[i];
-    const newChild = newChildren[i];
-    const existingNode = oldNodes[i];
-    if (oldChild === void 0 && newChild !== void 0) {
-      const node = renderValue(newChild, ctx);
-      parent.insertBefore(node, oldNodes[i + 1] ?? null);
-    } else if (oldChild !== void 0 && newChild !== void 0) {
-      patchValue(parent, existingNode, oldChild, newChild, ctx);
+  let rmIdx = 0;
+  for (let i = 0; i < oldChildren.length; i++) {
+    const child = oldChildren[i];
+    if (child == null || typeof child === "boolean") continue;
+    const key = getKey(child);
+    if (key === void 0) {
+      const node = parent.childNodes[rmIdx];
+      if (node) node.remove();
+    } else {
+      const isRemote = child && typeof child === "object" && child._placement === "remote";
+      if (!isRemote) rmIdx++;
     }
   }
-}
-function patchKeyedChildren(parent, oldChildren, newChildren, ctx) {
   const oldKeyMap = /* @__PURE__ */ new Map();
+  let domIdx = 0;
   for (let i = 0; i < oldChildren.length; i++) {
     const key = getKey(oldChildren[i]);
     if (key !== void 0) {
-      oldKeyMap.set(key, { vnode: oldChildren[i], node: parent.childNodes[i] || null });
+      const child = oldChildren[i];
+      const isRemote = child && typeof child === "object" && child._placement === "remote";
+      oldKeyMap.set(key, {
+        vnode: child,
+        node: isRemote ? null : parent.childNodes[domIdx] || null,
+        remote: !!isRemote,
+        index: domIdx
+      });
+      if (!isRemote) domIdx++;
     }
   }
   const newKeys = newChildren.map((c) => getKey(c));
@@ -458,35 +512,69 @@ function patchKeyedChildren(parent, oldChildren, newChildren, ctx) {
     if (!newKeys.includes(key)) {
       const entry = oldKeyMap.get(key);
       callRefCleanup(entry.vnode);
-      entry.node?.remove();
+      if (entry.node) entry.node?.remove();
       oldKeyMap.delete(key);
     }
   }
-  for (let i = oldChildren.length - 1; i >= 0; i--) {
-    const key = getKey(oldChildren[i]);
-    if (key === void 0) {
-      const node = parent.childNodes[i];
-      if (node) {
-        callRefCleanup(oldChildren[i]);
-        node.remove();
-      }
-    }
-  }
-  let insertBefore = parent.firstChild;
-  for (let i = newChildren.length - 1; i >= 0; i--) {
+  let lastIndex = -1;
+  let nextRef = parent.firstChild;
+  for (let i = 0; i < newChildren.length; i++) {
     const key = newKeys[i];
     const newChild = newChildren[i];
     const oldEntry = key !== void 0 ? oldKeyMap.get(key) : void 0;
-    if (oldEntry && oldEntry.node) {
-      parent.insertBefore(oldEntry.node, insertBefore);
-      insertBefore = oldEntry.node;
-      patchValue(parent, oldEntry.node, oldEntry.vnode, newChild, ctx);
+    const isRemote = newChild && typeof newChild === "object" && newChild._placement === "remote";
+    if (oldEntry) {
+      if (oldEntry.node) {
+        if (oldEntry.index < lastIndex) {
+          parent.insertBefore(oldEntry.node, nextRef);
+        }
+        lastIndex = Math.max(lastIndex, oldEntry.index);
+        patchValue(parent, oldEntry.node, oldEntry.vnode, newChild, ctx);
+        nextRef = (oldEntry.node.parentNode === parent ? oldEntry.node : parent.firstChild)?.nextSibling ?? null;
+      } else if (oldEntry.remote) {
+        patchPortal(oldEntry.vnode, newChild, ctx);
+      } else {
+        const newNode = patchValue(parent, null, oldEntry.vnode, newChild, ctx);
+        if (newNode != null) {
+          parent.insertBefore(newNode, nextRef);
+          nextRef = newNode.nextSibling;
+        }
+      }
+    } else if (isRemote) {
+      renderPortal(newChild, ctx);
     } else {
       const node = renderValue(newChild, ctx);
-      parent.insertBefore(node, insertBefore);
-      insertBefore = node;
+      if (node != null) {
+        parent.insertBefore(node, nextRef);
+        nextRef = node.nextSibling;
+      }
+    }
+  }
+}
+function childrenEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] !== b[i]) return false;
+    }
+    return true;
+  }
+  return a === b;
+}
+function componentPropsEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+  for (const key of keys) {
+    if (key === "key") continue;
+    if (key === "children") {
+      if (!childrenEqual(a[key], b[key])) return false;
+    } else if (a[key] !== b[key]) {
+      return false;
     }
   }
+  return true;
 }
 function cleanupPortalChildren(vnode) {
   const child = vnode._child;
@@ -519,10 +607,10 @@ function callRefCleanup(input) {
     }
   }
   if (typeof vnode.props?.ref === "function") vnode.props.ref(null);
-  if (vnode._portalEl) {
+  if (vnode._remoteEl) {
     cleanupPortalChildren(vnode);
-    vnode._portalEl.remove();
-    vnode._portalEl = void 0;
+    vnode._remoteEl.remove();
+    vnode._remoteEl = void 0;
   }
 }
@@ -536,15 +624,27 @@ function createApp() {
   let _rendering = false;
   let _dirtyBatch = /* @__PURE__ */ new Set();
   let _dirtyScheduled = false;
+  const _mediaRegistry = /* @__PURE__ */ new Map();
   function renderByIds(ids) {
     if (_rendering) return;
     _rendering = true;
     for (const id of ids) {
       const vnode = idRegistry.get(id);
       if (!vnode || !vnode._render) continue;
+      ctx.ui._dirtySet?.delete(id);
       const oldChild = vnode._child;
       const newChild = vnode._render(vnode.props);
       vnode._child = newChild;
+      if (oldChild && oldChild._placement === "remote" || newChild && newChild._placement === "remote") {
+        if (oldChild && newChild) {
+          patchPortal(oldChild, newChild, ctx);
+        } else if (newChild) {
+          renderPortal(newChild, ctx);
+        } else if (oldChild) {
+          callRefCleanup(oldChild);
+        }
+        continue;
+      }
       if (!vnode._parentNode && vnode._refNode) {
         ;
         vnode._parentNode = vnode._refNode.parentNode;
@@ -559,6 +659,9 @@ function createApp() {
         );
         if (newNode && newNode !== vnode._refNode) {
           vnode._refNode = newNode;
+        } else if (!newNode) {
+          ;
+          vnode._refNode = null;
         }
       }
     }
@@ -598,6 +701,12 @@ function createApp() {
       container.innerHTML = "";
       ctx.ui = {
         _selfId: "_wf_root",
+        // ── ctx 版本号（供三态 skip 判定） ──
+        _ctxVersion: 0,
+        _dirtySet: /* @__PURE__ */ new Set(),
+        bumpCtxVersion: function() {
+          this._ctxVersion++;
+        },
         /** 同步刷新（无参 = 当前组件，传参 = 指定组件列表） */
         render: function(ids) {
           if (!ids || ids.length === 0) {
@@ -616,7 +725,10 @@ function createApp() {
             else return;
           }
           for (const id of ids) {
-            if (id) _dirtyBatch.add(id);
+            if (id) {
+              _dirtyBatch.add(id);
+              ctx.ui._dirtySet.add(id);
+            }
           }
           if (!_dirtyScheduled) {
             _dirtyScheduled = true;
@@ -630,10 +742,68 @@ function createApp() {
         },
         /** 创建响应式状态容器：$.x = val 自动触发 dirty() */
         $: function() {
+          if (!this._$cache) {
+            const selfId = getSelfId(this);
+            this._$cache = createReactiveState(() => ctx.ui.dirty([selfId]));
+          }
+          return this._$cache;
+        },
+        /**
+         * 响应式媒体查询：注册监听，值变化时自动 dirty
+         *
+         * 用法：
+         *   const $ = ctx.ui.$()
+         *   ctx.ui.useMedia('(max-width: 640px)', (v) => { $.isMobile = v })
+         *
+         * callback 会立即执行一次（取当前值），之后在变化时再次执行
+         */
+        useMedia: function(query, callback) {
           const selfId = getSelfId(this);
-          return createReactiveState(() => {
-            if (selfId) ctx.ui.dirty([selfId]);
-          });
+          const key = `media:${selfId}:${query}`;
+          if (!_mediaRegistry.has(key)) {
+            const mql = window.matchMedia(query);
+            callback(mql.matches);
+            const handler = (e) => callback(e.matches);
+            mql.addEventListener("change", handler);
+            _mediaRegistry.set(key, { mql, handler });
+          }
+        },
+        /**
+         * 响应式断点：注册命名断点监听，值变化时自动 dirty
+         *
+         * 用法：
+         *   const $ = ctx.ui.$()
+         *   ctx.ui.useBreakpoint((vp) => { $.vp = vp })
+         *   // vp: 'mobile' | 'tablet' | 'desktop'
+         *
+         * 自定义断点：
+         *   ctx.ui.useBreakpoint(
+         *     { narrow: '(max-width: 480px)', wide: '(min-width: 1200px)' },
+         *     (vp) => { $.size = vp }
+         *   )
+         */
+        useBreakpoint: function(bpsOrCallback, callback) {
+          const bps = typeof bpsOrCallback === "function" ? { mobile: "(max-width: 639px)", tablet: "(min-width: 640px) and (max-width: 1023px)", desktop: "(min-width: 1024px)" } : bpsOrCallback;
+          const cb = typeof bpsOrCallback === "function" ? bpsOrCallback : callback;
+          const selfId = getSelfId(this);
+          const key = `bp:${selfId}`;
+          function evaluate() {
+            for (const [name, query] of Object.entries(bps)) {
+              if (window.matchMedia(query).matches) return name;
+            }
+            return Object.keys(bps)[0] ?? "";
+          }
+          if (!_mediaRegistry.has(key)) {
+            cb(evaluate());
+            const handlers = [];
+            for (const query of Object.values(bps)) {
+              const mql = window.matchMedia(query);
+              const handler = () => cb(evaluate());
+              mql.addEventListener("change", handler);
+              handlers.push(() => mql.removeEventListener("change", handler));
+            }
+            _mediaRegistry.set(key, { mql: null, handler: null });
+          }
         },
         /** 注册组件实例的自定义 ID（用于跨组件精准刷新） */
         selfId: function(name) {
@@ -790,12 +960,14 @@ function router(opts) {
         ctx.route = resolved2;
       }
       if (ctx.route?.title) document.title = ctx.route.title;
+      ctx.ui?.bumpCtxVersion?.();
       ctx.ui?.render();
     };
     const onPop = () => {
       const resolved2 = resolve(getPath());
       ctx.route = resolved2;
       if (ctx.route?.title) document.title = ctx.route.title;
+      ctx.ui?.bumpCtxVersion?.();
       ctx.ui?.render();
     };
     window.addEventListener("popstate", onPop);
@@ -1212,6 +1384,7 @@ function i18n(opts = {}) {
       merged = mergeLocales(pkg2, messages, components);
       state.locale = lang2;
       state.components = merged.components;
+      ctx?.ui?.bumpCtxVersion?.();
       ctx?.ui?.render();
     };
     return ctx;

package/dist/client/render.d.ts CHANGED Viewed

@@ -13,6 +13,12 @@
 import type { VNode } from './vnode.ts';
 import type { WfuiContext } from './types.ts';
 export declare const idRegistry: Map<string, VNode>;
-export declare function render(input: any, ctx: WfuiContext): Node;
+export declare function render(input: any, ctx: WfuiContext): Node | null;
+/** 首次渲染 Portal：创建远程容器、渲染子节点（不返回占位节点） */
+export declare function renderPortal(vnode: VNode, ctx: WfuiContext): void;
+/** 更新 Portal：复用远程容器，patch 子节点（不操作父 DOM） */
+export declare function patchPortal(oldV: VNode | null, newV: VNode, ctx: WfuiContext): void;
 export declare function patchValue(parent: Node, oldNode: Node | null, oldInput: any, newInput: any, ctx: WfuiContext): Node | null;
+/** 通知 ref 清理 + Portal 子容器清理 */
+export declare function callRefCleanup(input: any): void;
 export declare function mountVNode(container: Element, vnode: VNode, ctx: WfuiContext): void;

package/dist/client/vnode.d.ts CHANGED Viewed

@@ -15,8 +15,10 @@ export interface VNode {
     el?: Node;
     /** 子 VNode 缓存（用于 patchValue diff，避免重复执行组件） */
     _child?: any;
-    /** Portal 子容器 DOM */
-    _portalEl?: HTMLDivElement | undefined;
+    /** 远程 DOM 容器（Portal 等 remote VNode 的 DOM 所在处） */
+    _remoteEl?: HTMLElement | undefined;
+    /** VNode 的 DOM 归属：'local' 在父 DOM 树下，'remote' 在别处 */
+    _placement?: 'local' | 'remote';
     /** 两阶段组件的 render 函数（mount 返回的函数） */
     _render?: (props: any) => VNode | null;
     /** 组件实例 ID（如 '_wf_0'） */
@@ -25,6 +27,8 @@ export interface VNode {
     _parentNode?: Node;
     /** 组件输出的第一个 DOM 节点 */
     _refNode?: Node | null;
+    /** 组件 mount/render 时的 ctx 版本号（供三态 skip 判定） */
+    _ctxVersion?: number;
 }
 export type Component<P = {}> = (initProps: P, ctx: WfuiContext) => ((props: P) => VNode | null) | null;
 export declare const Fragment: unique symbol;

package/dist/components/index.js CHANGED Viewed

@@ -21,7 +21,8 @@ function createPortal(children, portalKey) {
   return {
     type: Portal,
     props: { children, portalKey },
-    key: portalKey ?? void 0
+    key: portalKey ?? void 0,
+    _placement: "remote"
   };
 }
@@ -1383,7 +1384,6 @@ function minuteOptions() {
 // src/components/DatePicker/DatePicker.ts
 var DatePicker = (_props, ctx) => {
-  const L = ctx?.i18n?.components?.DatePicker ?? {};
   let show = false;
   let selectedValue = "";
   const now = /* @__PURE__ */ new Date();
@@ -1398,6 +1398,7 @@ var DatePicker = (_props, ctx) => {
   let rangeEnd = null;
   let inputEl = null;
   return (props) => {
+    const L = ctx?.i18n?.components?.DatePicker ?? {};
     const { mode = "date", value, onChange, placeholder = L.placeholder ?? "\u9009\u62E9\u65E5\u671F", disabled } = props;
     const isOpen = show;
     const setOpen = (v) => {
@@ -2158,19 +2159,34 @@ function renderToolbar(items, active, isSource, onItem, customRender) {
 // src/components/Editor/tools/table.ts
 var MAX = 6;
 function insertTable(rows, cols) {
-  const tds = Array.from(
-    { length: cols },
-    (_, ci) => `<td${ci === 0 ? ' style="font-weight:var(--wf-font-weight-semibold,600)"' : ""}>&nbsp;</td>`
-  ).join("");
-  const rowsHtml = Array.from(
-    { length: rows },
-    (_, ri) => `<tr>${ri === 0 ? tds : tds.replace(/ style="[^"]*"/, "")}</tr>`
-  ).join("");
-  const html = `<div><table class="wf-editor-table"><tbody>${rowsHtml}</tbody></table></div>`;
-  try {
-    document.execCommand("insertHTML", false, html);
-  } catch {
+  const sel = window.getSelection();
+  if (!sel || !sel.rangeCount) return;
+  const range = sel.getRangeAt(0);
+  if (!range) return;
+  const table = document.createElement("table");
+  table.className = "wf-editor-table";
+  const tbody = document.createElement("tbody");
+  for (let ri = 0; ri < rows; ri++) {
+    const tr = document.createElement("tr");
+    for (let ci = 0; ci < cols; ci++) {
+      const td = document.createElement("td");
+      if (ri === 0) {
+        td.style.fontWeight = "var(--wf-font-weight-semibold,600)";
+      }
+      td.innerHTML = "&nbsp;";
+      tr.appendChild(td);
+    }
+    tbody.appendChild(tr);
   }
+  table.appendChild(tbody);
+  const wrapper = document.createElement("div");
+  wrapper.appendChild(table);
+  range.deleteContents();
+  range.insertNode(wrapper);
+  range.setStartAfter(wrapper);
+  range.collapse(true);
+  sel.removeAllRanges();
+  sel.addRange(range);
 }
 function renderTableGrid(hoverRow, hoverCol, onSelect, onHover, onLeave) {
   const grid = h("div", {
@@ -2203,8 +2219,18 @@ function renderTableGrid(hoverRow, hoverCol, onSelect, onHover, onLeave) {
 }
 // src/components/Editor/Editor.ts
+function shallowEqual(a, b) {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  const keys = Object.keys(a);
+  if (keys.length !== Object.keys(b).length) return false;
+  for (const k of keys) {
+    if (a[k] !== b[k]) return false;
+  }
+  return true;
+}
 var Editor = (_props, ctx) => {
-  let activeFormats = {};
+  let activeFormats = null;
   let showLinkInput = false;
   let linkUrl = "";
   let mode = "rich";
@@ -2338,9 +2364,11 @@ var Editor = (_props, ctx) => {
       showTableGrid = false;
       tableHoverRow = -1;
       tableHoverCol = -1;
-      ctx.ui.render();
+      console.log("[ED] table sel", "editorEl=", !!editorEl, "savedRange=", !!savedRange);
       restoreSelection();
+      console.log("[ED] table after restore", "rc=", window.getSelection()?.rangeCount, "focused=", document.activeElement?.className?.includes("wf-editor-content"));
       insertTable(rows, cols);
+      ctx.ui.render();
       if (editorEl && onChange) emitChange(editorEl.innerHTML);
     };
     const handleTableHover = (row, col) => {
@@ -2373,6 +2401,7 @@ var Editor = (_props, ctx) => {
       open: isRichMode && !!showTableGrid,
       onOpenChange: (v) => {
         showTableGrid = v;
+        if (v) saveSelection();
         ctx.ui.render();
       },
       content: tableGrid
@@ -2398,10 +2427,18 @@ var Editor = (_props, ctx) => {
     const handleMouseUp = () => {
       if (!isRichMode) return;
       saveSelection();
-      activeFormats = queryFormats();
-      ctx.ui.render();
+      const newFormats = queryFormats();
+      if (activeFormats === null) {
+        activeFormats = newFormats;
+        return;
+      }
+      if (!shallowEqual(activeFormats, newFormats)) {
+        activeFormats = newFormats;
+        ctx.ui.render();
+      }
     };
     const handleMouseDown = () => {
+      saveSelection();
       let needsRender = false;
       if (showLinkInput) {
         showLinkInput = false;
@@ -2527,7 +2564,7 @@ var Editor = (_props, ctx) => {
     return h("div", {
       class: `wf-editor${disabled ? " wf-editor--disabled" : ""}`
     }, [
-      !disabled && toolbarItems.length > 0 ? renderToolbar(toolbarItems, activeFormats, !isRichMode, handleToolbarItem, customRender) : null,
+      !disabled && toolbarItems.length > 0 ? renderToolbar(toolbarItems, activeFormats ?? {}, !isRichMode, handleToolbarItem, customRender) : null,
       editorBody,
       linkModal,
       imageModal,

package/dist/components/style.css CHANGED Viewed

@@ -110,6 +110,12 @@
   --wf-accent-color: var(--wf-color-primary);
   --wf-caret-color: var(--wf-color-primary);
+  /* ── 断点 ── */
+  --wf-bp-sm: 640px;
+  --wf-bp-md: 768px;
+  --wf-bp-lg: 1024px;
+  --wf-bp-xl: 1280px;
   /* ── 透明度 ── */
   --wf-opacity-disabled: 0.5;
   --wf-opacity-overlay: 0.4;
@@ -314,6 +320,9 @@ code {
   flex-direction: column;
   gap: var(--wf-gap, var(--wf-gap-md));
 }
+@media (min-width: 640px) { .wf-stack\@sm { flex-direction: row; align-items: var(--wf-align, center); } }
+@media (min-width: 768px) { .wf-stack\@md { flex-direction: row; align-items: var(--wf-align, center); } }
+@media (min-width: 1024px) { .wf-stack\@lg { flex-direction: row; align-items: var(--wf-align, center); } }
 /* stack-reverse — 纵向反向堆叠 */
 .wf-stack-reverse {
@@ -321,6 +330,9 @@ code {
   flex-direction: column-reverse;
   gap: var(--wf-gap, var(--wf-gap-md));
 }
+@media (min-width: 640px) { .wf-stack-reverse\@sm { flex-direction: row-reverse; align-items: var(--wf-align, center); } }
+@media (min-width: 768px) { .wf-stack-reverse\@md { flex-direction: row-reverse; align-items: var(--wf-align, center); } }
+@media (min-width: 1024px) { .wf-stack-reverse\@lg { flex-direction: row-reverse; align-items: var(--wf-align, center); } }
 /* row — 横向排列 */
 .wf-row {
@@ -329,6 +341,9 @@ code {
   gap: var(--wf-gap, var(--wf-gap-md));
   align-items: var(--wf-align, center);
 }
+@media (min-width: 640px) { .wf-row\@sm { flex-direction: row; flex-wrap: wrap; } }
+@media (min-width: 768px) { .wf-row\@md { flex-direction: row; flex-wrap: wrap; } }
+@media (min-width: 1024px) { .wf-row\@lg { flex-direction: row; flex-wrap: wrap; } }
 /* row-reverse — 横向反向排列 */
 .wf-row-reverse {
@@ -338,6 +353,9 @@ code {
   gap: var(--wf-gap, var(--wf-gap-md));
   align-items: var(--wf-align, center);
 }
+@media (min-width: 640px) { .wf-row-reverse\@sm { flex-direction: row-reverse; flex-wrap: wrap; } }
+@media (min-width: 768px) { .wf-row-reverse\@md { flex-direction: row-reverse; flex-wrap: wrap; } }
+@media (min-width: 1024px) { .wf-row-reverse\@lg { flex-direction: row-reverse; flex-wrap: wrap; } }
 /* split — 两端展开 */
 .wf-split {
@@ -486,11 +504,17 @@ code {
 .wf-hidden {
   display: none;
 }
+@media (min-width: 640px) { .wf-hidden\@sm { display: none; } }
+@media (min-width: 768px) { .wf-hidden\@md { display: none; } }
+@media (min-width: 1024px) { .wf-hidden\@lg { display: none; } }
 /* block — 块级显示 */
 .wf-block {
   display: block;
 }
+@media (min-width: 640px) { .wf-block\@sm { display: block; } }
+@media (min-width: 768px) { .wf-block\@md { display: block; } }
+@media (min-width: 1024px) { .wf-block\@lg { display: block; } }
 /* inline — 行内显示 */
 .wf-inline {

package/dist/layout/weifuwu-layout.css CHANGED Viewed

@@ -110,6 +110,12 @@
   --wf-accent-color: var(--wf-color-primary);
   --wf-caret-color: var(--wf-color-primary);
+  /* ── 断点 ── */
+  --wf-bp-sm: 640px;
+  --wf-bp-md: 768px;
+  --wf-bp-lg: 1024px;
+  --wf-bp-xl: 1280px;
   /* ── 透明度 ── */
   --wf-opacity-disabled: 0.5;
   --wf-opacity-overlay: 0.4;
@@ -314,6 +320,9 @@ code {
   flex-direction: column;
   gap: var(--wf-gap, var(--wf-gap-md));
 }
+@media (min-width: 640px) { .wf-stack\@sm { flex-direction: row; align-items: var(--wf-align, center); } }
+@media (min-width: 768px) { .wf-stack\@md { flex-direction: row; align-items: var(--wf-align, center); } }
+@media (min-width: 1024px) { .wf-stack\@lg { flex-direction: row; align-items: var(--wf-align, center); } }
 /* stack-reverse — 纵向反向堆叠 */
 .wf-stack-reverse {
@@ -321,6 +330,9 @@ code {
   flex-direction: column-reverse;
   gap: var(--wf-gap, var(--wf-gap-md));
 }
+@media (min-width: 640px) { .wf-stack-reverse\@sm { flex-direction: row-reverse; align-items: var(--wf-align, center); } }
+@media (min-width: 768px) { .wf-stack-reverse\@md { flex-direction: row-reverse; align-items: var(--wf-align, center); } }
+@media (min-width: 1024px) { .wf-stack-reverse\@lg { flex-direction: row-reverse; align-items: var(--wf-align, center); } }
 /* row — 横向排列 */
 .wf-row {
@@ -329,6 +341,9 @@ code {
   gap: var(--wf-gap, var(--wf-gap-md));
   align-items: var(--wf-align, center);
 }
+@media (min-width: 640px) { .wf-row\@sm { flex-direction: row; flex-wrap: wrap; } }
+@media (min-width: 768px) { .wf-row\@md { flex-direction: row; flex-wrap: wrap; } }
+@media (min-width: 1024px) { .wf-row\@lg { flex-direction: row; flex-wrap: wrap; } }
 /* row-reverse — 横向反向排列 */
 .wf-row-reverse {
@@ -338,6 +353,9 @@ code {
   gap: var(--wf-gap, var(--wf-gap-md));
   align-items: var(--wf-align, center);
 }
+@media (min-width: 640px) { .wf-row-reverse\@sm { flex-direction: row-reverse; flex-wrap: wrap; } }
+@media (min-width: 768px) { .wf-row-reverse\@md { flex-direction: row-reverse; flex-wrap: wrap; } }
+@media (min-width: 1024px) { .wf-row-reverse\@lg { flex-direction: row-reverse; flex-wrap: wrap; } }
 /* split — 两端展开 */
 .wf-split {
@@ -486,11 +504,17 @@ code {
 .wf-hidden {
   display: none;
 }
+@media (min-width: 640px) { .wf-hidden\@sm { display: none; } }
+@media (min-width: 768px) { .wf-hidden\@md { display: none; } }
+@media (min-width: 1024px) { .wf-hidden\@lg { display: none; } }
 /* block — 块级显示 */
 .wf-block {
   display: block;
 }
+@media (min-width: 640px) { .wf-block\@sm { display: block; } }
+@media (min-width: 768px) { .wf-block\@md { display: block; } }
+@media (min-width: 1024px) { .wf-block\@lg { display: block; } }
 /* inline — 行内显示 */
 .wf-inline {

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "weifuwu",
   "type": "module",
-  "version": "0.51.1",
+  "version": "0.53.0",
   "description": "AI SaaS framework — (req, ctx) => Response",
   "exports": {
     ".": {
@@ -33,7 +33,7 @@
     "prepublishOnly": "npm run build && tsc --emitDeclarationOnly --outdir dist",
     "typecheck": "tsc --noEmit",
     "pretest": "docker compose up -d --wait postgres redis 2>/dev/null; sleep 1",
-    "test": "node --env-file=.env --test 'src/test/**/*.test.ts'",
+    "test": "node --env-file=.env --test 'src/test/**/*.test.ts' 'src/components/**/*.test.ts'",
     "release": "node scripts/release.mjs",
     "release:dry": "node scripts/release.mjs --dry-run"
   },