weifuwu 0.94.1 → 0.95.0

package/dist/level3/vdom/hooks/field.ts

@@ -0,0 +1,97 @@
+/**
+ * vdom hooks — useField（表单字段行为契约——label/error/hint/aria 连接单源）
+ *
+ * 设计（2027-09——分层抽象 W5）：表单字段（Input/Select/DatePicker……）的
+ * label/required·error/hint 结构与 aria 连接（label for ↔ input id ·
+ * aria-invalid · aria-describedby · aria-required）重复手写实证——
+ * 契约化：字段作者只写输入面——标签/错误/提示/aria 由契约结构性保证。
+ *
+ * 结构类（labelClass/errClass/hintClass/reqClass/wrapErrClass）是皮
+ * （字段 CSS 定）——行为（属性/连接/态）契约内建。**渲染期 opts**（useOverlay
+ * 同模式——每次渲染读最新）。
+ *
+ * 用法：
+ *   const f = useField({ label, error, hint, required, name })
+ *   if (!f.hasWrap) return h('input', f.inputProps())
+ *   return h('div', { class: `wf-x-wrap${f.stateClass}` }, [
+ *     f.renderLabel(), h('input', f.inputProps()), f.renderError(), f.renderHint(),
+ *   ])
+ */
+import type { HookEnv } from './env.ts'
+import type { VNode } from '../../../level0/vdom/vnode.ts'
+import { h } from '../../../level0/vdom/vnode.ts'
+
+export interface FieldOptions {
+  label?: string
+  error?: string
+  hint?: string
+  required?: boolean
+  /** 连接 id 基（显式 id 或 name——label for ↔ input id） */
+  name?: string
+  id?: string
+  /** 包装面（错误态类——字段 CSS 的 --err 变体） */
+  wrapErrClass?: string
+  /** 标签/错误/提示的类（皮——字段 CSS） */
+  labelClass?: string
+  errClass?: string
+  hintClass?: string
+  reqClass?: string
+  /** 必填星字符（默认 *） */
+  reqChar?: string
+}
+
+export interface FieldHandle {
+  /** 包装与否（无 label/error/hint = 裸输入——Input 先例） */
+  hasWrap: boolean
+  /** 错误态类（'' 或 ' --err'——组件拼到 wrap class） */
+  stateClass: string
+  /** 输入 id（name/id 提供时——label for 连接） */
+  inputId: string | undefined
+  /** 输入面（id/aria-invalid/aria-describedby/aria-required） */
+  inputProps(): Record<string, unknown>
+  renderLabel(): VNode | null
+  renderError(): VNode | null
+  renderHint(): VNode | null
+}
+
+/** 表单字段契约（mount 期调用；opts 渲染期读最新——闭包引用） */
+export function useField(env: HookEnv, optsIn: FieldOptions): FieldHandle {
+  void env
+  let opts = optsIn
+  const id = () => opts.id ?? (opts.name ? `wf-${opts.name}` : undefined)
+  const baseId = () => id() ?? 'wf-field'
+  return {
+    get hasWrap() { return !!(opts.label || opts.error || opts.hint) },
+    get stateClass() { return opts.error ? ` ${opts.wrapErrClass ?? 'wf-field--err'}` : '' },
+    get inputId() { return id() },
+    inputProps() {
+      const p: Record<string, unknown> = {}
+      const i = id()
+      if (i) p.id = i
+      if (opts.error) p['aria-invalid'] = true
+      const desc: string[] = []
+      if (opts.error) desc.push(`${baseId()}-err`)
+      if (opts.hint && !opts.error) desc.push(`${baseId()}-hint`) // 与 renderHint 对齐（error 时 hint 不渲染）
+      if (desc.length) p['aria-describedby'] = desc.join(' ')
+      if (opts.required) p['aria-required'] = true
+      return p
+    },
+    renderLabel() {
+      if (opts.label == null && !opts.required) return null
+      const kids: VNode[] = []
+      if (opts.label != null) kids.push(opts.label as unknown as VNode)
+      if (opts.required) {
+        kids.push(h('span', { class: opts.reqClass ?? 'wf-field-req' }, opts.reqChar ?? '*'))
+      }
+      return h('label', { class: opts.labelClass, ...(id() ? { for: id() } : {}) }, kids)
+    },
+    renderError() {
+      return opts.error ? h('div', { class: opts.errClass, id: `${baseId()}-err` }, opts.error) : null
+    },
+    renderHint() {
+      return opts.hint && !opts.error
+        ? h('div', { class: opts.hintClass, id: `${baseId()}-hint` }, opts.hint)
+        : null
+    },
+  }
+}

package/dist/level3/vdom/hooks/input.ts

@@ -0,0 +1,92 @@
+/**
+ * vdom hooks — useControlledInput（受控输入——设计规则 §5.3 纪律）
+ *
+ * 核心（受控输入纪律）：**输入态不依赖受控 value 回流**——
+ * - keyword：内部输入态（输入期间 value 走内部态——不触发 onChange 回流——
+ *   父组件 render 不重挂 input——**焦点保持**）
+ * - setValue：触发 onChange（受控回流）
+ * - selectedLabel：选中回填（关闭后 input 回填选中 label——受控 onChange
+ *   不渲染时 props.value 不回流——input 空的坑）
+ * - **IME composition 门控**：中文输入法组合期间受控 value 重置打断——
+ *   isComposing 门控 + onCompositionEnd 处理最终值
+ */
+
+import type { HookEnv } from './env.ts'
+
+export interface ControlledInput {
+  /** 原受控选项（ui-dom 兼容——Mentions 读 controlled 原引用） */
+  controlled: { value?: string; onChange?: (v: string) => void; name?: string }
+  /** 受控值（渲染期读 props） */
+  value: string
+  /** 触发 onChange（受控回流） */
+  setValue(v: string): void
+  /** 内部输入态（输入期间——不回流——焦点保持） */
+  keyword: string
+  setKeyword(v: string): void
+  /** 选中回填（关闭后 input 回填选中 label） */
+  selectedLabel: string
+  setSelectedLabel(v: string): void
+  /** IME 组合门控（中文输入法） */
+  isComposing: boolean
+  onCompositionStart(): void
+  onCompositionEnd(): void
+}
+
+interface InputState {
+  keyword: string
+  selectedLabel: string
+  composing: boolean
+}
+
+/** 受控输入（渲染期调用——受控值读最新 props——内部态 hook 缓存） */
+export function useControlledInput(
+  env: HookEnv,
+  controlled: { value?: string; onChange?: (v: string) => void; name?: string },
+  opts?: { name?: string },
+): ControlledInput {
+  const idx = env.nextHookIndex()
+  const state = env.getHookState<InputState>(idx) ?? { keyword: '', selectedLabel: '', composing: false }
+  env.setHookState(idx, state)
+  const isControlled = controlled.value !== undefined
+  return {
+    controlled,
+    get value() {
+      return controlled.value ?? state.keyword
+    },
+    setValue(v: string): void {
+      if (isControlled) {
+        if (!controlled.onChange) {
+          console.warn(`[vdom] useControlledInput(${opts?.name ?? ''}) 受控缺 onChange 回调——交互静默失效`)
+        }
+        controlled.onChange?.(v)
+      } else {
+        state.keyword = v
+        env.requestRender()
+      }
+    },
+    get keyword() {
+      return state.keyword
+    },
+    setKeyword(v: string): void {
+      state.keyword = v // 内部态——不回流（输入期间焦点保持）
+      if (!state.composing) {
+        this.setValue(v) // 非组合期——同步触发 onChange（受控回流）
+      }
+    },
+    get selectedLabel() {
+      return state.selectedLabel
+    },
+    setSelectedLabel(v: string): void {
+      state.selectedLabel = v
+    },
+    get isComposing() {
+      return state.composing
+    },
+    onCompositionStart(): void {
+      state.composing = true
+    },
+    onCompositionEnd(): void {
+      state.composing = false
+    },
+  }
+}

package/dist/level3/vdom/hooks/observe.ts

@@ -0,0 +1,257 @@
+/**
+ * vdom hooks — observe（事件驱动响应式 hooks：useScrollPosition/useInView）
+ *
+ * 设计（设计规则 §4.2——hooks 是事件驱动重渲染——浏览器事件 → render——
+ * 与 $ 的「赋值自动」本质不同）：
+ * - useScrollPosition：全局 scroll + rAF 节流——y 响应式（视口/内部容器
+ *   通用）——scroll 事件 → 重渲染——unmount 清理
+ * - useInView：IntersectionObserver——isIn 响应式——IO 回调 → 重渲染——
+ *   unmount disconnect；环境无 IO（jsdom）→ 恒 false（测试注入 mock）
+ * - **目标元素未挂载**（首帧 ref 未就绪）→ 微任务重试注册（限次——防无限）
+ *
+ * 浏览器能力经 env.getBrowser()（零全局直接访问——设计规则 §5.5）。
+ */
+
+import type { HookEnv } from './env.ts'
+import { fromEventPattern, Subject, create } from '../../../level1/vdom/observable/index.ts'
+import { useObservable } from './use-observable.ts'
+
+/** useScrollPosition 选项（ui-dom 兼容对象形状——组件消费：{ getScroller }） */
+export interface UseScrollPositionOptions {
+  /** 滚动容器 getter（HTMLElement | Window——组件自管容器场景） */
+  getScroller?: () => HTMLElement | Window | null
+  /** 容器（string 选择器 / 元素） */
+  root?: string | HTMLElement
+}
+
+/** useScrollPosition 结果（**对象 getter 形态**——y/x 读时求值——mount
+ *  闭包持有永远最新——位置规则不存在；refresh 手动重算驱动） */
+export interface ScrollPosition {
+  readonly y: number
+  readonly x: number
+  /** 手动重算（组件调用方驱动——读当前滚动位置——不触发渲染） */
+  refresh(): void
+}
+
+interface ScrollState {
+  y: number
+  x: number
+  raf: number | null
+  handler: ((e: Event) => void) | null
+  retries: number
+}
+
+/** 目标解析（ui-dom 兼容：对象 { getScroller } / 字符串 / 元素 / 函数 / 缺省=窗口） */
+export type ScrollTarget = HTMLElement | (() => HTMLElement | null) | string | UseScrollPositionOptions
+
+function resolveScroller(target: ScrollTarget | undefined, win: Window, doc: Document | null): HTMLElement | Window {
+  if (typeof target === 'string') {
+    if (target === 'win' || target === 'window') return win
+    if (doc) return (doc.querySelector(target) as HTMLElement | null) ?? win
+    return win
+  }
+  if (target && typeof target === 'object' && !('nodeType' in target)) {
+    const opts = target as UseScrollPositionOptions
+    if (typeof opts.getScroller === 'function') {
+      const s = opts.getScroller()
+      if (s) return s
+      return win
+    }
+    if (opts.root) {
+      if (typeof opts.root === 'string') {
+        if (doc) return (doc.querySelector(opts.root) as HTMLElement | null) ?? win
+        return win
+      }
+      return opts.root
+    }
+    return win
+  }
+  return win
+}
+
+/** 滚动位置跟踪（视口或内部容器——rAF 节流——事件驱动重渲染） */
+export function useScrollPosition(
+  env: HookEnv,
+  target?: ScrollTarget,
+): ScrollPosition {
+  // **2027-08 迁移（波次 3）**：实现 = useObservable(滚动源)——订阅/退订/
+  // 重渲染/重试绑定全部统一——形状保留（对象 getter——调用方零改动）——
+  // refresh 语义升级：手动重算 → 流 next → **自动重渲染**（此前调用方驱动）
+  const refresh$ = new Subject<void>()
+  const state = useObservable(env, scrollSource$(env, target, refresh$), { y: 0, x: 0 })
+  return {
+    get y() { return state().y },
+    get x() { return state().x },
+    refresh: () => { refresh$.next() }, // 手动重算——流 next——自动重渲染
+  } as ScrollPosition
+}
+
+/** 滚动源（env 闭包 + 目标解析——**重试绑定防御保留**（`?? null` 语义））：
+ *  scroll(容器/window——capture 捕获) + rAF 节流 → next(readPos)——
+ *  目标未挂载（getScroller 返回 null）→ afterRender 重试（限 10 次）——
+ *  refresh$ 信号合流（手动重算入口） */
+function scrollSource$(
+  env: HookEnv,
+  target?: ScrollTarget,
+  refresh$?: Subject<void>,
+): import('../../../level1/vdom/observable/index.ts').Observable<{ y: number; x: number }> {
+  const win = env.getBrowser()?.window
+  const doc = env.getBrowser()?.document ?? null
+  return create<{ y: number; x: number }>((obs) => {
+    if (!win) { obs.next({ y: 0, x: 0 }); obs.complete(); return () => {} }
+    let raf: number | undefined
+    let handler: ((e?: Event) => void) | null = null
+    let scroller: HTMLElement | Window | null = null
+    let retries = 0
+
+    const getScroller = (): HTMLElement | Window | null => {
+      if (typeof target === 'function') return target()
+      if (target && typeof target === 'object' && !('nodeType' in target)) {
+        const opts = target as UseScrollPositionOptions
+        if (typeof opts.getScroller === 'function') return opts.getScroller() ?? null
+        if (opts.root) {
+          if (typeof opts.root === 'string') {
+            if (doc) return (doc.querySelector(opts.root) as HTMLElement | null) ?? win
+            return win
+          }
+          return opts.root
+        }
+        return win
+      }
+      return win
+    }
+    const readPos = (s: HTMLElement | Window | null): { y: number; x: number } => {
+      if (!s) return { y: 0, x: 0 }
+      if (s === win) return { y: win.scrollY || 0, x: win.scrollX || 0 }
+      return { y: (s as HTMLElement).scrollTop, x: (s as HTMLElement).scrollLeft }
+    }
+    const emit = (): void => { obs.next(readPos(scroller)) }
+
+    const ensure = (): void => {
+      if (handler) return
+      scroller = getScroller()
+      if (!scroller) {
+        // **重试绑定防御（`?? null` 语义——已修 bug 逻辑保留）**：
+        // 首帧 el 未挂载 target()=null——afterRender 重试（限次——防无限）
+        if (retries++ < 10) env.scheduleAfterRender(ensure)
+        return
+      }
+      const onScroll = (): void => {
+        if (raf !== undefined) return
+        raf = win.requestAnimationFrame(() => {
+          raf = undefined
+          emit()
+        })
+      }
+      scroller.addEventListener('scroll', onScroll, { passive: true } as never)
+      handler = onScroll
+      emit() // 注册即读初值
+    }
+    ensure()
+    // **refresh = ensure + emit（2027-XX——Affix 容器级 target 实证修复）**：
+    // 此前 refresh 只 emit()——目标后挂载（getScroller 首帧 null → 重试耗尽）
+    // 后 refresh 永不重试绑定 → 滚动源永久丢失（容器滚动零响应）。
+    // ensure 幂等（已绑定即跳过）——refresh 语义 = 重新解析目标 + 读值
+    const refreshSub = refresh$?.subscribe({ next: () => { ensure(); emit() } })
+    return () => {
+      refreshSub?.unsubscribe()
+      if (raf !== undefined) win.cancelAnimationFrame(raf)
+      if (handler && scroller) scroller.removeEventListener('scroll', handler)
+      handler = null
+    }
+  })
+}
+
+/** useInView 选项（ui-dom 兼容对象形状——组件消费：{ root, threshold, target }） */
+export interface UseInViewOptions {
+  /** 可见性变化回调（ui-dom 兼容——InfiniteScroll 用——双参 (entry, isIn)） */
+  onChange?(entry: unknown, isIn: boolean): void
+  /** 根容器（元素或渲染期 getter——ui-dom 兼容） */
+  root?: HTMLElement | null | (() => HTMLElement | Element | null)
+  /** 阈值（值或渲染期 getter） */
+  threshold?: number | number[] | (() => number | number[])
+  /** 边距（字符串或渲染期 getter——ui-dom 渲染期函数形状） */
+  rootMargin?: string | (() => string)
+  target?: HTMLElement | (() => HTMLElement | null)
+}
+
+/** useInView 结果（**对象 getter 形态**——isIn/ready 读时求值——mount
+ *  闭包持有永远最新） */
+export interface InView {
+  readonly isIn: boolean
+  /** 绑定 ref（el 挂载 → 观察；null → 断开） */
+  ref(el: HTMLElement | null): void
+  /** 手动开始观察（组件自管 el 场景——BackTop/InView） */
+  observe(el: HTMLElement): void
+  /** 停止观察 */
+  disconnect(): void
+  /** 是否已注册（BackTop 用：ready && !isIn → 显示） */
+  readonly ready: boolean
+}
+
+interface InViewState {
+  isIn: boolean
+  io: { disconnect: () => void } | null
+  retries: number
+  ready: boolean
+}
+
+type IoCtor = new (cb: (entries: Array<{ isIntersecting: boolean }>) => void) => {
+  observe: (el: Element) => void
+  disconnect: () => void
+}
+
+/** 可见性观察（IntersectionObserver——IO 回调 → 重渲染——环境无 IO → 恒 false） */
+export function useInView(
+  env: HookEnv,
+  options?: UseInViewOptions | HTMLElement | (() => HTMLElement | null),
+): InView {
+  const idx = env.nextHookIndex()
+  const state = env.getHookState<InViewState>(idx) ?? { isIn: false, io: null, retries: 0, ready: false }
+  env.setHookState(idx, state)
+  const win = env.getBrowser()?.window as (Window & { IntersectionObserver?: IoCtor }) | null
+  const IO = win?.IntersectionObserver
+  // 目标解析（对象 { target } / 元素 / 函数 / 对象无 target = 组件自管 observe）
+  const opts = options && typeof options === 'object' && !('nodeType' in options)
+    ? options as UseInViewOptions
+    : undefined
+  const target = opts?.target ?? (typeof options === 'function' ? options : options && 'nodeType' in options ? options : undefined)
+  // 渲染期 getter 解析（ui-dom 函数形状——rootMargin/threshold）
+  const rootMargin = typeof opts?.rootMargin === 'function' ? opts.rootMargin() : opts?.rootMargin
+  const threshold = typeof opts?.threshold === 'function' ? opts.threshold() : opts?.threshold
+  const rootEl = typeof opts?.root === 'function' ? opts.root() as HTMLElement | null : (opts?.root ?? null)
+
+  const startObserve = (el: HTMLElement | null): void => {
+    if (!IO || !el || state.io) return
+    const io = new (IO as unknown as new (cb: (entries: Array<{ isIntersecting: boolean }>) => void, opts?: Record<string, unknown>) => {
+      observe: (el: Element) => void; disconnect: () => void
+    })((entries) => {
+      const e = entries[0]
+      if (e && e.isIntersecting !== state.isIn) {
+        state.isIn = e.isIntersecting
+        opts?.onChange?.(e, e.isIntersecting)
+        env.requestRender()
+      }
+    }, { root: rootEl ?? undefined, rootMargin, threshold })
+    io.observe(el)
+    state.io = io
+    state.ready = true
+    env.onUnmount(() => state.io?.disconnect())
+  }
+
+  if (IO && !state.io) {
+    const el = typeof target === 'function' ? target() : (target ?? null)
+    if (el) {
+      startObserve(el)
+    } else if (target !== undefined && state.retries++ < 10) {
+      env.scheduleAfterRender(() => startObserve(typeof target === 'function' ? target() : (target ?? null)))
+    }
+  }
+  return {
+    get isIn() { return state.isIn },
+    get ready() { return state.ready },
+    ref: (el: HTMLElement | null) => { if (el) startObserve(el); else state.io?.disconnect() },
+    observe: (el: HTMLElement) => startObserve(el),
+    disconnect: () => { state.io?.disconnect(); state.io = null },
+  }
+}

package/dist/level3/vdom/hooks/overlay.d.ts

@@ -0,0 +1,60 @@
+/**
+ * vdom hooks — useOverlay（弹层行为契约——开/关/焦点/滚动锁/Esc 单源）
+ *
+ * 设计（2027-09——分层抽象 W2）：弹层家族（Modal/Drawer/ActionSheet）的
+ * 行为面（open 同步 openPopup 生命周期 · trapFocus · lockScroll ·
+ * 遮罩点击 · Esc 关闭 · presence 退场）**契约化**——组件作者只写**皮**
+ * （overlay/panel 的 class 与内容）——行为正确性由契约结构性保证。
+ *
+ * 分工（与 popup-manager 的关系）：useOverlay 是 popup-manager（openPopup）
+ * 的**组件作者友好封装**（受控同步模式 Modal 先例的契约化）——float 定位
+ * 族（Popover/Tooltip）不在此契约（正交组合 usePopupPosition——未来
+ * usePopover 契约 = useOverlay + usePopupPosition）。
+ *
+ * 用法：
+ *   const ov = ctx.ui.useOverlay({ open, onOpenChange, role: 'dialog', maskClosable })
+ *   const root = h('div', { class: 'wf-modal' }, [
+ *     h('div', { ...ov.maskProps, class: 'wf-modal-overlay' }),
+ *     h('div', { ...ov.panelProps, class: 'wf-modal-content' }, content),
+ *   ])
+ *   ov.sync(root)   // 渲染期同步（openPopup 生命周期）
+ *   return root
+ */
+import type { HookEnv } from './env.ts';
+import type { VNode } from '../../../level0/vdom/vnode.ts';
+export interface OverlayOptions {
+    /** 受控 open（父层） */
+    open?: boolean;
+    /** 关闭上抛（遮罩/Esc/close()） */
+    onOpenChange?: (v: boolean) => void;
+    /** 面板角色（默认 dialog——alertdialog 场景覆盖） */
+    role?: string;
+    /** Tab 焦点困禁（默认 true——`{...panelProps}` 面板内循环） */
+    trapFocus?: boolean;
+    /** 滚动锁（默认 true——body 锁定 + 焦点归还） */
+    lockScroll?: boolean;
+    /** 遮罩点击关闭（默认 true——危险确认 false） */
+    maskClosable?: boolean;
+    /** Esc 关闭（默认 true——危险确认可 false） */
+    closeOnEscape?: boolean;
+    /** presence 退场动画（退场 class → animationend → 卸载） */
+    presence?: boolean;
+}
+export interface OverlayHandle {
+    /** 遮罩面（onClick 行为——类名是皮——组件拼接） */
+    maskProps: {
+        onClick?: (e: Event) => void;
+    };
+    /** 面板面（role/aria-modal——类名是皮） */
+    panelProps: {
+        role: string;
+        'aria-modal': true;
+    };
+    /** 关闭（上抛 onOpenChange(false)） */
+    close(): void;
+    /** 渲染期同步（openPopup 生命周期——open 变化/内容更新；latestOpts
+     *  渲染期最新配置——缺省用 mount 初值） */
+    sync(root: () => VNode, latestOpts?: OverlayOptions): void;
+}
+/** 弹层行为契约（mount 期调用——状态闭包；sync 渲染期调用） */
+export declare function useOverlay(env: HookEnv, opts: OverlayOptions): OverlayHandle;

package/dist/level3/vdom/hooks/overlay.ts

@@ -0,0 +1,105 @@
+/**
+ * vdom hooks — useOverlay（弹层行为契约——开/关/焦点/滚动锁/Esc 单源）
+ *
+ * 设计（2027-09——分层抽象 W2）：弹层家族（Modal/Drawer/ActionSheet）的
+ * 行为面（open 同步 openPopup 生命周期 · trapFocus · lockScroll ·
+ * 遮罩点击 · Esc 关闭 · presence 退场）**契约化**——组件作者只写**皮**
+ * （overlay/panel 的 class 与内容）——行为正确性由契约结构性保证。
+ *
+ * 分工（与 popup-manager 的关系）：useOverlay 是 popup-manager（openPopup）
+ * 的**组件作者友好封装**（受控同步模式 Modal 先例的契约化）——float 定位
+ * 族（Popover/Tooltip）不在此契约（正交组合 usePopupPosition——未来
+ * usePopover 契约 = useOverlay + usePopupPosition）。
+ *
+ * 用法：
+ *   const ov = ctx.ui.useOverlay({ open, onOpenChange, role: 'dialog', maskClosable })
+ *   const root = h('div', { class: 'wf-modal' }, [
+ *     h('div', { ...ov.maskProps, class: 'wf-modal-overlay' }),
+ *     h('div', { ...ov.panelProps, class: 'wf-modal-content' }, content),
+ *   ])
+ *   ov.sync(root)   // 渲染期同步（openPopup 生命周期）
+ *   return root
+ */
+import type { HookEnv } from './env.ts'
+import { openPopup, type PopupHandle } from './popup-manager.ts'
+import { useGlobalKey } from './basic.ts'
+import type { VNode } from '../../../level0/vdom/vnode.ts'
+
+export interface OverlayOptions {
+  /** 受控 open（父层） */
+  open?: boolean
+  /** 关闭上抛（遮罩/Esc/close()） */
+  onOpenChange?: (v: boolean) => void
+  /** 面板角色（默认 dialog——alertdialog 场景覆盖） */
+  role?: string
+  /** Tab 焦点困禁（默认 true——`{...panelProps}` 面板内循环） */
+  trapFocus?: boolean
+  /** 滚动锁（默认 true——body 锁定 + 焦点归还） */
+  lockScroll?: boolean
+  /** 遮罩点击关闭（默认 true——危险确认 false） */
+  maskClosable?: boolean
+  /** Esc 关闭（默认 true——危险确认可 false） */
+  closeOnEscape?: boolean
+  /** presence 退场动画（退场 class → animationend → 卸载） */
+  presence?: boolean
+}
+
+export interface OverlayHandle {
+  /** 遮罩面（onClick 行为——类名是皮——组件拼接） */
+  maskProps: { onClick?: (e: Event) => void }
+  /** 面板面（role/aria-modal——类名是皮） */
+  panelProps: { role: string; 'aria-modal': true }
+  /** 关闭（上抛 onOpenChange(false)） */
+  close(): void
+  /** 渲染期同步（openPopup 生命周期——open 变化/内容更新；latestOpts
+   *  渲染期最新配置——缺省用 mount 初值） */
+  sync(root: () => VNode, latestOpts?: OverlayOptions): void
+}
+
+/** 弹层行为契约（mount 期调用——状态闭包；sync 渲染期调用） */
+export function useOverlay(env: HookEnv, opts: OverlayOptions): OverlayHandle {
+  let handle: PopupHandle | null = null
+  let latest = opts // 渲染期最新（close/mask 读最新配置）
+
+  const maskProps = {
+    onClick: (e: Event) => {
+      if (latest.maskClosable !== false && e.target === e.currentTarget) close()
+    },
+  }
+  const panelProps = { role: opts.role ?? 'dialog', 'aria-modal': true as const }
+  const close = () => latest.onOpenChange?.(false)
+
+  const sync = (getContent: () => VNode, latestOpts?: OverlayOptions) => {
+    if (latestOpts) latest = latestOpts
+    const open = !!latest.open
+    if (open && !handle) {
+      handle = openPopup(env, {
+        key: 'overlay',
+        presence: !!latest.presence,
+        trapFocus: latest.trapFocus !== false,
+        lockScroll: latest.lockScroll !== false,
+        positioning: 'none',
+        closeOnOutside: false, // 遮罩点击语义组件自控（maskProps）
+        closeOnEscape: false,  // Esc 契约自控（mount 期 useGlobalKey——open 期间）
+        content: getContent,
+        onClose: () => { handle = null },
+      })
+    } else if (!open && handle) {
+      handle.update(getContent())
+      handle.close()
+      handle = null
+    } else if (handle) {
+      handle.update(getContent())
+    }
+  }
+
+  // Esc 关闭（mount 期注册——hook 顺序稳定；open 期间才触发——焦点在
+  // trap 外也可关闭；closeOnEscape=false（危险确认）时短路）
+  useGlobalKey(env, (e: KeyboardEvent) => {
+    if (e.key === 'Escape' && handle?.open && latest.closeOnEscape !== false) close()
+  })
+
+  env.onUnmount?.(() => { if (handle) handle.close() })
+
+  return { maskProps, panelProps, close, sync }
+}