@h-ai/ui 0.1.0-alpha.47 → 0.1.0-alpha.49

package/README.md

@@ -174,7 +174,7 @@ components/
 | `Modal`   | 模态框 | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose` |
 | `Drawer`  | 抽屉   | `open`, `position`, `title`, `size`, `width`, `resizable`, `widthStorageKey` |
 | `Confirm` | 确认框 | `open`, `title`, `message`, `variant`, `onconfirm`      |
-| `Popover` | 弹出层 | `open`, `position`, `trigger`, `offset`                 |
+| `Popover` | 弹出层 | `open`, `position`, `trigger`, `offset`, `portal`       |
 
 #### 数据展示
 

package/dist/components/compounds/Pagination.svelte

@@ -51,23 +51,28 @@
       : 'w-[2.5rem] shrink-0 [&>.fieldset]:m-0 [&>.fieldset]:min-w-0',
   )
 
+  let jumperValue = $state(String(page))
+
   function goToPage(p: number) {
-    if (p >= 1 && p <= totalPages && p !== page) {
-      page = p
-      onchange?.(p)
+    const clamped = Math.max(1, Math.min(totalPages, Math.round(p)))
+    if (clamped !== page) {
+      page = clamped
+      jumperValue = String(clamped)
+      onchange?.(clamped)
     }
   }
 
-  let jumperValue = $state('')
-
   function handleJump() {
     const p = Number.parseInt(jumperValue, 10)
     if (!Number.isNaN(p)) {
       goToPage(p)
-      jumperValue = ''
     }
   }
 
+  function handleJumperBlur() {
+    handleJump()
+  }
+
   function handlePageSizeChange(value: string) {
     const next = Number.parseInt(value, 10)
     if (!Number.isNaN(next) && next !== pageSize) {
@@ -150,6 +155,7 @@
             max={totalPages}
             bind:value={jumperValue}
             onkeydown={(e: KeyboardEvent & { currentTarget: HTMLInputElement }) => e.key === 'Enter' && handleJump()}
+            onblur={handleJumperBlur}
           />
         </div>
         <span class={tableTextClass}>{labels.page ?? uiM('pagination_page')}</span>

package/dist/components/compounds/Popover.svelte

@@ -9,13 +9,15 @@
 -->
 <script lang='ts'>
   import type { DataAttributes, PopoverProps } from '../../types.js'
-  import { cn, getDataAttributes } from '../../utils.js'
+  import { tick } from 'svelte'
+  import { cn, getDataAttributes, portal as portalAction } from '../../utils.js'
 
   let {
     open = $bindable(false),
     position = 'bottom',
     trigger = 'click',
     offset = 8,
+    portal = false,
     class: className = '',
     onopen,
     onclose,
@@ -27,6 +29,10 @@
   const dataAttributes = $derived(getDataAttributes(restProps))
   let triggerElement = $state<HTMLDivElement | null>(null)
   let popoverElement = $state<HTMLDivElement | null>(null)
+  /** portal 模式下的 fixed 坐标；每次滚动或缩放后重新计算。 */
+  let portalStyle = $state('')
+  /** 首帧布局收敛后的二次定位帧，关闭时必须取消避免过期写入。 */
+  let portalPositionFrame: number | undefined = $state()
 
   const positionClass = $derived({
     top: 'bottom-full left-1/2 -translate-x-1/2 mb-2',
@@ -42,6 +48,51 @@
     right: 'right-full top-1/2 -translate-y-1/2 border-r-base-100 border-t-transparent border-l-transparent border-b-transparent',
   }[position])
 
+  /** portal 模式下不再依赖相对容器，改用视口坐标并在边缘自动收敛。 */
+  function updatePortalPosition(): void {
+    if (!triggerElement || !popoverElement) {
+      return
+    }
+
+    const triggerRect = triggerElement.getBoundingClientRect()
+    const popoverRect = popoverElement.getBoundingClientRect()
+    const viewportPadding = 8
+    const gap = offset
+    const maxLeft = Math.max(viewportPadding, window.innerWidth - popoverRect.width - viewportPadding)
+    const maxTop = Math.max(viewportPadding, window.innerHeight - popoverRect.height - viewportPadding)
+    let left = triggerRect.left + (triggerRect.width - popoverRect.width) / 2
+    let top = triggerRect.bottom + gap
+
+    if (position === 'top') {
+      top = triggerRect.top - popoverRect.height - gap
+    }
+    else if (position === 'left') {
+      left = triggerRect.left - popoverRect.width - gap
+      top = triggerRect.top + (triggerRect.height - popoverRect.height) / 2
+    }
+    else if (position === 'right') {
+      left = triggerRect.right + gap
+      top = triggerRect.top + (triggerRect.height - popoverRect.height) / 2
+    }
+
+    portalStyle = `position:fixed;left:${Math.round(Math.min(Math.max(viewportPadding, left), maxLeft))}px;top:${Math.round(Math.min(Math.max(viewportPadding, top), maxTop))}px;z-index:1200;`
+  }
+
+  /** 等 portal 挂载完成后复测，避免首帧按未完成内容高度定位。 */
+  async function scheduleSettledPortalPosition(): Promise<void> {
+    await tick()
+    if (!open || !portal) {
+      return
+    }
+
+    portalPositionFrame = window.requestAnimationFrame(() => {
+      portalPositionFrame = undefined
+      if (open && portal) {
+        updatePortalPosition()
+      }
+    })
+  }
+
   function handleOpen() {
     open = true
     onopen?.()
@@ -95,6 +146,27 @@
       document.removeEventListener('click', handleClickOutside)
     }
   })
+
+  // portal 内容脱离原始相对定位容器后，以 fixed 坐标跟随触发器滚动和缩放。
+  $effect(() => {
+    if (!open || !portal) {
+      return
+    }
+
+    updatePortalPosition()
+    void scheduleSettledPortalPosition()
+    const listenerOptions = { passive: true, capture: true } as const
+    window.addEventListener('scroll', updatePortalPosition, listenerOptions)
+    window.addEventListener('resize', updatePortalPosition)
+    return () => {
+      if (portalPositionFrame !== undefined) {
+        window.cancelAnimationFrame(portalPositionFrame)
+        portalPositionFrame = undefined
+      }
+      window.removeEventListener('scroll', updatePortalPosition, listenerOptions)
+      window.removeEventListener('resize', updatePortalPosition)
+    }
+  })
 </script>
 
 <div {...dataAttributes}
@@ -117,23 +189,37 @@
     {/if}
   </div>
 
-  <!-- 弹出内容 -->
+  <!-- 弹出内容；portal 模式用于逃逸滚动容器的 overflow 裁剪。 -->
   {#if open}
-    <div
-      bind:this={popoverElement}
-      class={cn(
-        'absolute z-50 bg-base-100 rounded-box shadow-lg border border-base-200 p-4',
-        positionClass,
-      )}
-      style='--offset: {offset}px'
-      role='dialog'
-    >
-      <!-- 箭头 -->
-      <div class={cn('absolute w-0 h-0 border-8', arrowClass)}></div>
-
-      {#if children}
-        {@render children()}
-      {/if}
-    </div>
+    {#if portal}
+      <div
+        bind:this={popoverElement}
+        use:portalAction
+        class='fixed z-50 rounded-box border border-base-200 bg-base-100 p-4 shadow-lg'
+        style={portalStyle}
+        role='dialog'
+      >
+        {#if children}
+          {@render children()}
+        {/if}
+      </div>
+    {:else}
+      <div
+        bind:this={popoverElement}
+        class={cn(
+          'absolute z-50 bg-base-100 rounded-box shadow-lg border border-base-200 p-4',
+          positionClass,
+        )}
+        style='--offset: {offset}px'
+        role='dialog'
+      >
+        <!-- 箭头 -->
+        <div class={cn('absolute w-0 h-0 border-8', arrowClass)}></div>
+
+        {#if children}
+          {@render children()}
+        {/if}
+      </div>
+    {/if}
   {/if}
 </div>

package/dist/components/compounds/Tooltip.svelte

@@ -2,7 +2,9 @@
   =============================================================================
   @h-ai/ui - Tooltip 组件
   =============================================================================
-  提示框组件
+  提示框组件，支持两种渲染模式：
+  - 默认：DaisyUI CSS 伪元素（::before），轻量无 JS 开销
+  - portal：通过 document.body 渲染，不受父容器 overflow 裁剪
 
   使用 Svelte 5 Runes ($props, $derived)
   =============================================================================
@@ -14,12 +16,17 @@
   const {
     content,
     position = 'top',
+    delay,
     class: className = '',
     children,
+    portal = false,
     ...restProps
   }: TooltipProps & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
+
+  // ─── CSS 模式（默认） ───
+
   const positionMap = {
     top: 'tooltip-top',
     right: 'tooltip-right',
@@ -34,10 +41,124 @@
       className,
     ),
   )
+
+  // ─── Portal 模式 ───
+
+  let triggerEl = $state<HTMLDivElement>()
+  let portalEl: HTMLDivElement | null = null
+
+  function getClass(opacity: string): string {
+    return cn(
+      'pointer-events-none fixed z-[9999] rounded-md bg-base-content px-2 py-1 text-xs text-base-100 shadow-md',
+      className,
+      opacity,
+    )
+  }
+
+  function ensurePortal(): HTMLDivElement {
+    if (!portalEl && typeof document !== 'undefined') {
+      portalEl = document.createElement('div')
+      portalEl.setAttribute('role', 'tooltip')
+      portalEl.className = getClass('opacity-0')
+      document.body.appendChild(portalEl)
+    }
+    return portalEl!
+  }
+
+  function updatePosition(): string {
+    if (!triggerEl)
+      return ''
+
+    const rect = triggerEl.getBoundingClientRect()
+    const gap = 6
+    let top: number
+    let left: number
+    let transform: string
+
+    switch (position) {
+      case 'top':
+        top = rect.top - gap
+        left = rect.left + rect.width / 2
+        transform = 'translate(-50%,-100%)'
+        break
+      case 'bottom':
+        top = rect.bottom + gap
+        left = rect.left + rect.width / 2
+        transform = 'translateX(-50%)'
+        break
+      case 'left':
+        top = rect.top + rect.height / 2
+        left = rect.left - gap
+        transform = 'translate(-100%,-50%)'
+        break
+      case 'right':
+        top = rect.top + rect.height / 2
+        left = rect.right + gap
+        transform = 'translateY(-50%)'
+        break
+    }
+
+    return `top:${top}px;left:${left}px;transform:${transform};`
+  }
+
+  let showTimer: ReturnType<typeof setTimeout> | undefined
+
+  function show() {
+    if (delay) {
+      showTimer = setTimeout(doShow, delay)
+    }
+    else {
+      doShow()
+    }
+  }
+
+  function doShow() {
+    const el = ensurePortal()
+    el.className = getClass('opacity-100')
+    el.style.cssText = updatePosition()
+    el.textContent = content
+  }
+
+  function hide() {
+    if (showTimer) {
+      clearTimeout(showTimer)
+      showTimer = undefined
+    }
+    if (portalEl) {
+      portalEl.className = getClass('opacity-0')
+    }
+  }
+
+  $effect(() => {
+    return () => {
+      if (showTimer)
+        clearTimeout(showTimer)
+      if (portalEl?.parentNode) {
+        portalEl.parentNode.removeChild(portalEl)
+        portalEl = null
+      }
+    }
+  })
 </script>
 
-<div {...dataAttributes} class={tooltipClass} data-tip={content}>
-  {#if children}
-    {@render children()}
-  {/if}
-</div>
+{#if portal}
+  <div
+    {...dataAttributes}
+    bind:this={triggerEl}
+    class='inline-flex'
+    onmouseenter={show}
+    onmouseleave={hide}
+    onfocusin={show}
+    onfocusout={hide}
+  >
+    {#if children}
+      {@render children()}
+    {/if}
+  </div>
+{:else}
+  <div {...dataAttributes} class={tooltipClass} data-tip={content}>
+    {#if children}
+      {@render children()}
+    {/if}
+  </div>
+{/if}

package/dist/components/scenes/crud/CrudPage.svelte

@@ -655,7 +655,7 @@
   {/if}
 
   <!-- 搜索 + 过滤栏 -->
-  {#if searchable || filterFields.length > 0}
+  {#if searchable || filterFields.length > 0 || toolbarLeading || toolbarActions}
     {#if toolbarStyle === 'toolbar'}
       <TableToolbar
         {searchable}
@@ -699,7 +699,7 @@
   <Card padding='none' class={listCardClass}>
     {#if card}
       <!-- 卡片视图使用独立滚动容器，分页栏始终保留在容器外。 -->
-      <div class='min-h-0 flex-1 overflow-auto'>
+      <div class='min-h-0 flex-1 overflow-auto pt-2'>
         {#if data.items.length > 0}
           <div class='grid min-h-full grid-cols-[repeat(auto-fill,minmax(min(100%,18rem),1fr))] content-start gap-3'>
             {#each data.items as item (String(item[keyField]))}

package/dist/index.d.ts

@@ -6,6 +6,7 @@
  */
 export * from './components/index.js';
 export * from './i18n.svelte.js';
+export * from './internal/browser-safety.js';
 export * from './message.svelte.js';
 export * from './messagebox.svelte.js';
 export * from './theme-config.js';

package/dist/index.js

@@ -8,6 +8,8 @@
 export * from './components/index.js';
 // ─── i18n 国际化（Paraglide 辅助工具） ───
 export * from './i18n.svelte.js';
+// ─── 浏览器能力安全辅助（剪贴板、localStorage 等降级方案） ───
+export * from './internal/browser-safety.js';
 // ─── Message 轻量消息提示（类似 ElementUI Message） ───
 export * from './message.svelte.js';
 // ─── MessageBox 命令式弹框（类似 ElementUI MessageBox） ───

package/dist/internal/browser-safety.d.ts

@@ -20,7 +20,8 @@ export declare function writeStoredValue(key: string, value: string): boolean;
 /**
  * 安全写入剪贴板。
  *
- * 在不安全上下文、旧 WebView 或浏览器策略禁用时直接返回 false，
- * 让上层决定是否展示成功反馈。
+ * 优先使用现代 Clipboard API；在不安全上下文（HTTP）、旧 WebView
+ * 或浏览器策略禁用时回退到 `document.execCommand('copy')`，
+ * 确保尽可能多的环境下复制操作可用。
  */
 export declare function writeTextToClipboard(text: string): Promise<boolean>;

package/dist/internal/browser-safety.js

@@ -41,16 +41,37 @@ export function writeStoredValue(key, value) {
 /**
  * 安全写入剪贴板。
  *
- * 在不安全上下文、旧 WebView 或浏览器策略禁用时直接返回 false，
- * 让上层决定是否展示成功反馈。
+ * 优先使用现代 Clipboard API；在不安全上下文（HTTP）、旧 WebView
+ * 或浏览器策略禁用时回退到 `document.execCommand('copy')`，
+ * 确保尽可能多的环境下复制操作可用。
  */
 export async function writeTextToClipboard(text) {
-    if (typeof navigator === 'undefined' || !navigator.clipboard?.writeText) {
+    if (typeof navigator === 'undefined') {
+        return false;
+    }
+    // 现代 Clipboard API（仅安全上下文可用）
+    if (navigator.clipboard?.writeText) {
+        try {
+            await navigator.clipboard.writeText(text);
+            return true;
+        }
+        catch {
+            // Clipboard API 失败时继续尝试 fallback
+        }
+    }
+    // fallback：textarea + execCommand（兼容 HTTP、旧浏览器）
+    if (typeof document === 'undefined') {
         return false;
     }
     try {
-        await navigator.clipboard.writeText(text);
-        return true;
+        const textarea = document.createElement('textarea');
+        textarea.value = text;
+        textarea.style.cssText = 'position:fixed;left:-9999px;top:-9999px;opacity:0';
+        document.body.appendChild(textarea);
+        textarea.select();
+        const ok = document.execCommand('copy');
+        document.body.removeChild(textarea);
+        return ok;
     }
     catch {
         return false;

package/dist/types.d.ts

@@ -516,6 +516,11 @@ export interface TooltipProps extends DataAttributes {
     class?: string;
     /** 触发元素插槽 */
     children?: Snippet;
+    /**
+     * 启用 portal 模式：提示内容通过 document.body 渲染，
+     * 不受父容器 overflow 裁剪。适用于表格、滚动容器等场景。
+     */
+    portal?: boolean;
 }
 /**
  * 加载属性
@@ -727,8 +732,8 @@ export interface DropdownItem {
 export interface DropdownProps extends DataAttributes {
     /** 菜单项 */
     items: DropdownItem[];
-    /** 触发方式 */
-    trigger?: 'click' | 'hover';
+    /** 触发方式；`manual` 由外部完全控制 open 状态。 */
+    trigger?: 'click' | 'hover' | 'manual';
     /** 位置 */
     position?: Position;
     /** 对齐 */
@@ -977,6 +982,8 @@ export interface PopoverProps extends DataAttributes {
     trigger?: 'click' | 'hover';
     /** 偏移量 */
     offset?: number;
+    /** 是否将内容挂到 body，以逃逸祖先 overflow 和堆叠上下文。 */
+    portal?: boolean;
     /** 自定义类名 */
     class?: string;
     /** 打开事件 */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.47",
+  "version": "0.1.0-alpha.49",
   "description": "Hai Framework UI component library for Svelte 5 Runes.",
   "license": "Apache-2.0",
   "svelte": "./dist/index.js",
@@ -52,7 +52,7 @@
     "mermaid": "^11.12.0",
     "shiki": "^4.0.2",
     "tailwind-merge": "^3.5.0",
-    "@h-ai/core": "0.1.0-alpha.47"
+    "@h-ai/core": "0.1.0-alpha.49"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",