@h-ai/ui 0.1.0-alpha.48 → 0.1.0-alpha.50

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`       |
 
 #### 数据展示
 
@@ -211,7 +211,7 @@ components/
 
 | 组件         | 描述     | 主要属性                                     |
 | ------------ | -------- | -------------------------------------------- |
-| `Tabs`       | 标签页   | `items`, `active`, `type`, `size`            |
+| `Tabs`       | 标签页   | `items`, `active`, `type`, `size`, `lazy`, `onactivate` |
 | `Pagination` | 分页（统一 table 风格） | `page`, `total`, `pageSize`, `showTotal`, `showJumper`, `showSizeChanger`, `showPageInfo`, `showFirstLast` |
 | `Breadcrumb` | 面包屑   | `items`, `separator`                         |
 | `Steps`      | 步骤条   | `items`, `current`, `direction`, `clickable` |
@@ -334,7 +334,7 @@ components/
 
 | 组件                 | 描述         | 主要属性 / 能力 |
 | -------------------- | ------------ | ---------------- |
-| `CrudPage`           | CRUD 主页面  | `crud`, `data`, `permissions`, `form`, `pagination`, `density`, `detailColumns`, `showHeader`, `toolbarStyle`, `toolbarLeading`, `toolbarActions`, `card`, `tableCell`, `onrowclick`, `sortableColumns`, `nav` |
+| `CrudPage`           | CRUD 主页面  | `crud`, `data`, `permissions`, `form`, `pagination`, `density`, `detailColumns`, `showHeader`, `toolbarStyle`, `toolbarLeading`, `toolbarActions`, `card`, `tableCell`, `onrowclick`, `sortableColumns`, `nav`, `loading`, `loaded`, `error`, `onRetry`, `keepPreviousData` |
 | `CrudFilterBar`      | 过滤工具栏（搜索 + 多类型过滤 + 重置） | `filterFields`, `searchValue`, `onsearch`, `onfilterchange`, `onreset` |
 | `CrudDetailPanel`    | 详情面板（抽屉/弹窗） | `open`, `item`, `fields`, `variant`, `drawerWidth`, `modalSize` |
 | `CrudEditPanel`      | 编辑面板（抽屉/弹窗） | `open`, `fields`, `variant`, `drawerWidth`, `modalSize`, `onsubmit` |
@@ -361,6 +361,21 @@ components/
 > `pagination` 配置分页栏（始终显示）：`showSizeChanger`、`pageSizeOptions`、`showJumper`、`showTotal` 默认开启；紧凑视图可用 `showPageInfo` 关闭页码文案、`showFirstLast` 关闭首页 / 末页按钮。
 >
 > `density` 配置列表密度：`'normal'`（默认）或 `'compact'`（紧凑）。它只影响列表行、行内操作、分页与创建/编辑/详情表单元素，不影响页头与筛选栏。
+>
+> `CrudPage` 受控加载态：`loading` / `loaded` / `error` / `onRetry` / `keepPreviousData`。仅当 `loaded && total === 0` 时才展示空状态（避免首次请求未回时误显“暂无数据”）；首次查询展示“查询中”；失败且无可用数据时展示错误与重试（`onRetry`）；`keepPreviousData`（默认 true）在刷新/失败时保留旧数据。
+>
+> 纯客户端（无 SvelteKit SSR）可用框架级 `defineCrud` + `createCrudController` 托管 `data` 与 `nav`，自带 latest-wins（seq + AbortSignal）、失败保留旧数据、惰性加载与并发去重：
+>
+> ```svelte
+> <script>
+>   import { CrudPage, createCrudController, defineCrud } from '@h-ai/ui'
+>   const crud = defineCrud({ name: 'user', label: '用户', fields: [/* ... */], api: { list: params => listUsers(params) } })
+>   const c = createCrudController(crud) // 惰性页签传 { autoLoad: false }，首次激活时 c.load()
+> </script>
+> <CrudPage {crud} data={c.data} nav={c.nav} loading={c.loading} loaded={c.loaded} error={c.error} onRetry={c.reload} />
+> ```
+>
+> `Tabs` 支持惰性页签：`lazy` 开启后未激活过的页签内容不渲染（`children` 提供 `isActivated(key)` 判断），`onactivate(key)` 在页签首次激活时触发一次，适合配合 `createCrudController({ autoLoad: false })` 在首次可见时才加载。
 
 ## 使用示例
 
@@ -382,6 +397,8 @@ components/
 <ToastContainer />
 ```
 
+> 已内置 `notifySuccess` / `notifyError` / `notifyInfo` / `notifyWarning` 封装，业务应用无需自建 toast 工具文件：`notifyError(err, fallback?)` 接受 `Error` 或字符串并内置兑底文案，默认成功 3s / 失败 5s。
+
 ### Message 消息提示
 
 ```svelte

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/Tabs.svelte

@@ -4,6 +4,7 @@
 -->
 <script lang='ts'>
   import type { DataAttributes, TabsProps } from '../../types.js'
+  import { SvelteSet } from 'svelte/reactivity'
   import { cn, getDataAttributes } from '../../utils.js'
   import BareButton from '../primitives/BareButton.svelte'
 
@@ -14,11 +15,16 @@
     type = 'line',
     class: className = '',
     onchange,
+    onactivate,
+    lazy = false,
     children,
     ...restProps
   }: TabsProps & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
+  // 已激活过的页签集合，用于惰性挂载（不预加载不可见页签）。
+  const activatedKeys = new SvelteSet<string>()
+
   // 默认选中第一个
   $effect(() => {
     if (!active && items.length > 0) {
@@ -26,6 +32,19 @@
     }
   })
 
+  // 记录激活过的页签，并在首次激活时回调一次，供惰性加载对应内容。
+  $effect(() => {
+    if (active && !activatedKeys.has(active)) {
+      activatedKeys.add(active)
+      onactivate?.(active)
+    }
+  })
+
+  /** 指定页签是否已激活过；非惰性模式下恒为 true（内容全部预挂载）。 */
+  function isActivated(key: string): boolean {
+    return !lazy || activatedKeys.has(key)
+  }
+
   const typeMap = {
     line: 'tabs-border',
     card: 'tabs-box',
@@ -77,6 +96,6 @@
 
 {#if children}
   <div class='py-4'>
-    {@render children()}
+    {@render children({ active, isActivated })}
   </div>
 {/if}

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}