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

package/README.md

@@ -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/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/scenes/crud/CrudPage.svelte

@@ -159,6 +159,11 @@
     onerror,
     basePath = '',
     nav = createBrowserNavAdapter(),
+    loading = false,
+    loaded = true,
+    error,
+    onRetry,
+    keepPreviousData = true,
     class: className = '',
     ...restProps
   }: {
@@ -219,12 +224,42 @@
      * 以获得客户端跳转 + invalidateAll 体验。
      */
     nav?: NavAdapter
+    /** 列表是否正在加载；由外部控制器（`createCrudController`）提供，用于展示查询中占位。 */
+    loading?: boolean
+    /**
+     * 是否至少成功加载过一次。仅当 `loaded && total === 0` 时展示空状态，
+     * 避免首次请求未回时误显示“暂无数据”。默认 true 以兼容 SvelteKit SSR（数据随页面就绪）。
+     */
+    loaded?: boolean
+    /** 最新一轮加载错误；无可用数据时展示错误信息与重试按钮。 */
+    error?: Error | string
+    /** 点击“重试”回调；通常传入控制器的 `reload`。 */
+    onRetry?: () => void
+    /** 失败或刷新时是否保留旧数据（默认 true）；为 false 时加载中展示查询中占位而非旧列表。 */
+    keepPreviousData?: boolean
     /** 根节点自定义 class。 */
     class?: string
   } & DataAttributes = $props()
 
   /** 透传到根节点的 data-* 属性。 */
   const dataAttributes = $derived(getDataAttributes(restProps))
+
+  // ─── 加载 / 空 / 错误展示态 ───
+
+  /** 归一化错误文案；error 允许是 Error 或字符串。 */
+  const errorMessage = $derived(error ? (typeof error === 'string' ? error : error.message) : '')
+  /** 是否已有可展示的数据行。 */
+  const hasItems = $derived(data.items.length > 0)
+  /** 加载失败且无可保留数据：整块替换为错误信息 + 重试。 */
+  const showErrorState = $derived(!!error && (!hasItems || !keepPreviousData))
+  /** 首次查询（或不保留旧数据时）尚无数据：展示查询中占位，避免误显示空状态。 */
+  const showQuerying = $derived(loading && !showErrorState && (!hasItems || !keepPreviousData))
+  /** 常规列表区块（含空状态）；仅此区块内才可能出现“暂无数据”。 */
+  const showListRegion = $derived(!showErrorState && !showQuerying)
+  /** 列表可见但仍在刷新（保留旧数据）：顶部细进度条提示。 */
+  const showRefreshing = $derived(showListRegion && loading && hasItems)
+  /** 保留旧数据时的错误细条 + 重试，不打断浏览已有列表。 */
+  const showErrorBanner = $derived(showListRegion && !!error && hasItems)
   // ─── 状态 ───
 
   /** 表格行的主键字段。 */
@@ -697,101 +732,143 @@
 
   <!-- 数据列表 -->
   <Card padding='none' class={listCardClass}>
-    {#if card}
-      <!-- 卡片视图使用独立滚动容器，分页栏始终保留在容器外。 -->
-      <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]))}
-              {@render card(item)}
-            {/each}
-          </div>
-        {:else}
-          <div class='flex min-h-full items-center justify-center px-4 text-sm text-base-content/55'>
-            {uiM('data_table_empty')}
-          </div>
+    {#if showQuerying}
+      <!-- 首次查询：展示查询中占位，避免请求未回时误显示“暂无数据” -->
+      <div class='flex min-h-40 flex-1 flex-col items-center justify-center gap-2 px-4 py-10 text-sm text-base-content/55'>
+        <span class='loading loading-spinner loading-md text-base-content/40'></span>
+        <span>{uiM('crud_loading')}</span>
+      </div>
+    {:else if showErrorState}
+      <!-- 加载失败且无可保留数据：错误信息 + 重试 -->
+      <div class='flex min-h-40 flex-1 flex-col items-center justify-center gap-3 px-4 py-10 text-sm'>
+        <span class='icon-[tabler--alert-triangle] size-8 text-error/70'></span>
+        <p class='max-w-md text-center text-base-content/70'>{errorMessage || uiM('crud_load_failed')}</p>
+        {#if onRetry}
+          <Button size={actionButtonSize} onclick={() => onRetry?.()}>
+            <span class='icon-[tabler--refresh] mr-1 size-4'></span>
+            {uiM('crud_retry')}
+          </Button>
         {/if}
       </div>
     {:else}
-      <!-- DataTable 自身同时承接横向和纵向滚动，确保 sticky 表头与数据行共享滚动上下文。 -->
-      <DataTable
-        data={data.items}
-        columns={dtColumns}
-        keyField={keyField}
-        loading={false}
-        sortKey={sortBy || undefined}
-        sortDir={sortBy ? sortDirection : null}
-        onsort={handleSort}
-        class='min-h-0 min-w-0 flex-1 overflow-auto'
-        {density}
-        cell={tableCell}
-        {onrowclick}
-      >
-        {#snippet actions(item)}
-          {#if rowClickDetail}
-            <IconButton
-              variant='ghost'
-              size={actionButtonSize}
-              ariaLabel={uiM('crud_detail')}
-              onclick={(event) => {
-                event.stopPropagation()
-                openDetail(item)
-              }}
-            >
-              <span class='icon-[tabler--eye] {actionIconClass}'></span>
-            </IconButton>
-          {/if}
-          {#if canUpdate}
-            <IconButton
-              variant='ghost'
-              size={actionButtonSize}
-              ariaLabel={uiM('crud_edit')}
-              onclick={(event) => {
-                event.stopPropagation()
-                openEdit(item)
-              }}
-            >
-              <span class='icon-[tabler--edit] {actionIconClass}'></span>
-            </IconButton>
-          {/if}
-          {#if canDelete}
-            <IconButton
-              variant='ghost'
-              size={actionButtonSize}
-              ariaLabel={uiM('crud_delete')}
-              onclick={(event) => {
-                event.stopPropagation()
-                requestDelete(item)
-              }}
-              class='hover:text-error'
-            >
-              <span class='icon-[tabler--trash] {actionIconClass}'></span>
-            </IconButton>
+      {#if showErrorBanner}
+        <!-- 保留旧数据时的错误细条：不打断浏览，仍提供重试 -->
+        <div role='alert' class='flex items-center gap-2 border-b border-error/20 bg-error/10 px-3 py-2 text-xs text-error'>
+          <span class='icon-[tabler--alert-triangle] size-4 shrink-0'></span>
+          <span class='min-w-0 flex-1 truncate'>{errorMessage || uiM('crud_load_failed')}</span>
+          {#if onRetry}
+            <button type='button' class='shrink-0 font-medium underline underline-offset-2' onclick={() => onRetry?.()}>{uiM('crud_retry')}</button>
           {/if}
-          {#if listItemActions}
-            {@render listItemActions(item)}
+        </div>
+      {/if}
+      {#if showRefreshing}
+        <!-- 保留旧数据的刷新态：顶部细进度提示 -->
+        <div class='h-0.5 w-full overflow-hidden'>
+          <div class='h-full w-1/3 animate-pulse rounded-full bg-primary/60'></div>
+        </div>
+      {/if}
+      {#if card}
+        <!-- 卡片视图使用独立滚动容器，分页栏始终保留在容器外。 -->
+        <div class='min-h-0 flex-1 overflow-auto pt-2'>
+          {#if hasItems}
+            <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]))}
+                {@render card(item)}
+              {/each}
+            </div>
+          {:else if loaded}
+            <div class='flex min-h-full items-center justify-center px-4 text-sm text-base-content/55'>
+              {uiM('data_table_empty')}
+            </div>
+          {:else}
+            <!-- 惰性页签尚未激活：既未加载也无数据，留白不显示空状态 -->
+            <div class='min-h-full'></div>
           {/if}
-        {/snippet}
-      </DataTable>
+        </div>
+      {:else if loaded || hasItems}
+        <!-- DataTable 自身同时承接横向和纵向滚动，确保 sticky 表头与数据行共享滚动上下文。 -->
+        <DataTable
+          data={data.items}
+          columns={dtColumns}
+          keyField={keyField}
+          loading={false}
+          sortKey={sortBy || undefined}
+          sortDir={sortBy ? sortDirection : null}
+          onsort={handleSort}
+          class='min-h-0 min-w-0 flex-1 overflow-auto'
+          {density}
+          cell={tableCell}
+          {onrowclick}
+        >
+          {#snippet actions(item)}
+            {#if rowClickDetail}
+              <IconButton
+                variant='ghost'
+                size={actionButtonSize}
+                ariaLabel={uiM('crud_detail')}
+                onclick={(event) => {
+                  event.stopPropagation()
+                  openDetail(item)
+                }}
+              >
+                <span class='icon-[tabler--eye] {actionIconClass}'></span>
+              </IconButton>
+            {/if}
+            {#if canUpdate}
+              <IconButton
+                variant='ghost'
+                size={actionButtonSize}
+                ariaLabel={uiM('crud_edit')}
+                onclick={(event) => {
+                  event.stopPropagation()
+                  openEdit(item)
+                }}
+              >
+                <span class='icon-[tabler--edit] {actionIconClass}'></span>
+              </IconButton>
+            {/if}
+            {#if canDelete}
+              <IconButton
+                variant='ghost'
+                size={actionButtonSize}
+                ariaLabel={uiM('crud_delete')}
+                onclick={(event) => {
+                  event.stopPropagation()
+                  requestDelete(item)
+                }}
+                class='hover:text-error'
+              >
+                <span class='icon-[tabler--trash] {actionIconClass}'></span>
+              </IconButton>
+            {/if}
+            {#if listItemActions}
+              {@render listItemActions(item)}
+            {/if}
+          {/snippet}
+        </DataTable>
+      {:else}
+        <!-- 惰性页签未激活：既未加载也无数据，留白不显示空状态 -->
+        <div class='min-h-40 flex-1'></div>
+      {/if}
+
+      <!-- 分页栏：始终显示，支持每页条数选择与跳页（shadcn table 风格） -->
+      <div class={paginationBarClass}>
+        <Pagination
+          page={data.page}
+          total={data.total}
+          pageSize={data.pageSize}
+          size={paginationSize}
+          showTotal={paginationShowTotal}
+          showJumper={paginationShowJumper}
+          showSizeChanger={paginationShowSizeChanger}
+          showPageInfo={paginationShowPageInfo}
+          showFirstLast={paginationShowFirstLast}
+          pageSizeOptions={paginationPageSizeOptions}
+          onchange={handlePageChange}
+          onpagesizechange={handlePageSizeChange}
+        />
+      </div>
     {/if}
-
-    <!-- 分页栏：始终显示，支持每页条数选择与跳页（shadcn table 风格） -->
-    <div class={paginationBarClass}>
-      <Pagination
-        page={data.page}
-        total={data.total}
-        pageSize={data.pageSize}
-        size={paginationSize}
-        showTotal={paginationShowTotal}
-        showJumper={paginationShowJumper}
-        showSizeChanger={paginationShowSizeChanger}
-        showPageInfo={paginationShowPageInfo}
-        showFirstLast={paginationShowFirstLast}
-        pageSizeOptions={paginationPageSizeOptions}
-        onchange={handlePageChange}
-        onpagesizechange={handlePageSizeChange}
-      />
-    </div>
   </Card>
 </div>
 

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

@@ -188,6 +188,19 @@ type $$ComponentProps = {
      * 以获得客户端跳转 + invalidateAll 体验。
      */
     nav?: NavAdapter;
+    /** 列表是否正在加载；由外部控制器（`createCrudController`）提供，用于展示查询中占位。 */
+    loading?: boolean;
+    /**
+     * 是否至少成功加载过一次。仅当 `loaded && total === 0` 时展示空状态，
+     * 避免首次请求未回时误显示“暂无数据”。默认 true 以兼容 SvelteKit SSR（数据随页面就绪）。
+     */
+    loaded?: boolean;
+    /** 最新一轮加载错误；无可用数据时展示错误信息与重试按钮。 */
+    error?: Error | string;
+    /** 点击“重试”回调；通常传入控制器的 `reload`。 */
+    onRetry?: () => void;
+    /** 失败或刷新时是否保留旧数据（默认 true）；为 false 时加载中展示查询中占位而非旧列表。 */
+    keepPreviousData?: boolean;
     /** 根节点自定义 class。 */
     class?: string;
 } & DataAttributes;

package/dist/components/scenes/crud/crud-controller.svelte.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @h-ai/ui — CRUD 控制器（SPA 数据 + 导航托管）
+ *
+ * 为 `CrudPage` 提供两个框架级适配器，业务应用无需在各自项目里重复实现：
+ *   1. `defineCrud`：由声明式资源定义生成 `CrudPage` 所需的 `crud` 对象（字段筛选、列映射、默认值），
+ *      不依赖 `@h-ai/kit`，纯 SPA / Tauri / Capacitor 均可直接使用。
+ *   2. `createCrudController`：在纯客户端（无 SvelteKit SSR）下托管 `CrudPage` 的 `data` 与 `nav`，
+ *      把 `CrudPage` 通过 URL query 同步的搜索/过滤/分页参数解析回本地状态并重新拉取列表。
+ *
+ * 控制器特性：latest-wins（seq + AbortSignal 双保险）、失败保留旧数据、惰性加载、并发去重、
+ * 查询串回填地址栏（保留 pathname 与 hash，不整页跳转）。
+ *
+ * @module crud-controller
+ */
+import type { PaginatedResult } from '@h-ai/core';
+import type { NavAdapter } from './nav-adapter.js';
+/** 字段展示形式；与 `CrudEditPanel` / `CrudFilterBar` 支持的类型对齐，保留 `string` 以兼容 `@h-ai/kit`。 */
+export type CrudFieldType = 'text' | 'string' | 'textarea' | 'select' | 'radio' | 'multi-select' | 'boolean' | 'checkbox' | 'email' | 'url' | 'tel' | 'password' | 'number' | 'date' | 'datetime' | 'date-range' | 'custom';
+/** 可解析为字符串的文本值（支持 i18n 函数）。 */
+export type CrudText = string | (() => string);
+/** 选项项（select / radio / multi-select）。 */
+export interface CrudOption {
+    label: string;
+    value: string | number | boolean;
+}
+/** 字段定义（与 `CrudPage` 的字段模型对齐）。 */
+export interface CrudFieldDef {
+    /** 字段 id（对应数据对象的属性名）。 */
+    id: string;
+    /** 字段标签（支持 i18n 函数）。 */
+    label: CrudText;
+    /** 字段类型。 */
+    type: CrudFieldType;
+    /** 是否在列表展示（默认 true）。 */
+    inList?: boolean;
+    /** 是否可过滤（默认 false）。 */
+    filterable?: boolean;
+    /** 是否只读（编辑态禁用）。 */
+    readonly?: boolean;
+    /** 是否在新建表单出现（默认 true）。 */
+    inCreate?: boolean;
+    /** 是否在编辑表单出现（默认 true）。 */
+    inEdit?: boolean;
+    /** 是否在详情出现（默认 true）。 */
+    inDetail?: boolean;
+    /** 选项（select / radio / multi-select），支持工厂函数。 */
+    options?: CrudOption[] | (() => CrudOption[]);
+    /** 校验规则。 */
+    validation?: {
+        required?: boolean;
+        min?: number;
+        max?: number;
+        pattern?: string;
+        message?: string;
+    };
+    /** 列宽（CSS）。 */
+    width?: string;
+    /** 列对齐。 */
+    align?: 'left' | 'center' | 'right';
+    /** 列表单元格自定义渲染。 */
+    render?: (value: unknown, item: Record<string, unknown>) => string;
+    /** 占位文本。 */
+    placeholder?: CrudText;
+    /** 日期范围起始值 key（仅 date-range，默认 `${id}Start`）。 */
+    startKey?: string;
+    /** 日期范围结束值 key（仅 date-range，默认 `${id}End`）。 */
+    endKey?: string;
+    /** 默认值（新建时）。 */
+    defaultValue?: unknown;
+    /** 排序权重（升序）。 */
+    order?: number;
+}
+/** 列表请求附加项；用于 latest-wins 取消旧请求。 */
+export interface CrudListOptions {
+    /** 取消信号；旧请求被新请求取代时触发 abort。 */
+    signal?: AbortSignal;
+}
+/** CRUD API 集合。列表返回标准 `PaginatedResult<T>`，避免各页面重复 page/pageSize/total 映射。 */
+export interface CrudApi<T> {
+    /** 分页列表；第二参数携带取消信号，实现方可透传给 fetch。 */
+    list: (params: Record<string, unknown>, options?: CrudListOptions) => Promise<PaginatedResult<T>>;
+    /** 按主键获取单条。 */
+    get?: (id: string) => Promise<T | null>;
+    /** 创建一条记录。 */
+    create?: (data: Partial<T>) => Promise<T>;
+    /** 更新一条记录。 */
+    update?: (id: string, data: Partial<T>) => Promise<T>;
+    /** 删除一条记录。 */
+    remove?: (id: string) => Promise<void>;
+}
+/** 资源定义。 */
+export interface CrudResource<T> {
+    /** 资源名称（用于识别业务实体）。 */
+    name: string;
+    /** 资源标题（支持 i18n 函数）。 */
+    label: CrudText;
+    /** 主键字段（默认 `id`）。 */
+    keyField?: string;
+    /** 字段定义列表。 */
+    fields: CrudFieldDef[];
+    /** 默认分页条数（默认 10）。 */
+    defaultPageSize?: number;
+    /** 是否显示搜索框（默认 true）。 */
+    searchable?: boolean;
+    /** 搜索框占位文案。 */
+    searchPlaceholder?: CrudText;
+    /** 资源 CRUD API。 */
+    api: CrudApi<T>;
+}
+/** DataTable 列定义（适配 `CrudPage`）。 */
+export interface CrudTableColumn {
+    key: string;
+    label: string;
+    width?: string;
+    align?: 'left' | 'center' | 'right';
+    render?: (item: Record<string, unknown>) => string;
+}
+/** `CrudPage` 所需的 crud 对象形状（`defineCrud` 的返回值）。 */
+export interface CrudDef<T> {
+    resource: CrudResource<T>;
+    getListFields: () => CrudFieldDef[];
+    getFilterFields: () => CrudFieldDef[];
+    getCreateFields: () => CrudFieldDef[];
+    getEditFields: () => CrudFieldDef[];
+    getDetailFields: () => CrudFieldDef[];
+    toTableColumns: () => CrudTableColumn[];
+    getDefaultValues: () => Record<string, unknown>;
+    api: CrudApi<T>;
+}
+/** `CrudPage` 的 `data` 形状。 */
+export interface CrudData<T> {
+    items: T[];
+    total: number;
+    page: number;
+    pageSize: number;
+    filters: Record<string, unknown>;
+}
+/** CRUD 控制器：托管列表数据与 SPA 导航适配器。 */
+export interface CrudController<T> {
+    /** 传给 `<CrudPage data={...}>` 的响应式数据对象。 */
+    readonly data: CrudData<T>;
+    /** 传给 `<CrudPage nav={...}>` 的导航适配器（仅同步 query，不整页跳转）。 */
+    readonly nav: NavAdapter;
+    /** 首次或按需拉取当前参数；惰性页签用它在首次激活时启动查询。 */
+    load: () => Promise<void>;
+    /** 主动按当前参数重新拉取（写操作后或重试触发）。 */
+    reload: () => Promise<void>;
+    /** 当前是否有最新一轮列表请求尚未结束。 */
+    readonly loading: boolean;
+    /** 是否至少成功取得过一次列表响应。 */
+    readonly loaded: boolean;
+    /** 最新一轮请求错误；已有成功数据时仍保留原列表。 */
+    readonly error: Error | undefined;
+}
+/** CRUD 控制器创建选项。 */
+export interface CrudControllerOptions {
+    /** 是否在创建后立即加载；不可见 / 惰性页签应设为 false（默认 true）。 */
+    autoLoad?: boolean;
+    /** 请求失败或重新拉取时是否保留已有数据（默认 true，避免闪现空列表）。 */
+    keepPreviousData?: boolean;
+    /** 是否把查询串回填浏览器地址栏（保留 pathname 与 hash，默认 true）。 */
+    syncUrl?: boolean;
+}
+/**
+ * 映射分页结果的 `items`，保留 total / page / pageSize。
+ *
+ * @description 标准 `PaginatedResult<T>` 适配器：业务页面只需转换条目本身，
+ *   无需重复搬运分页元数据，配合 `CrudApi.list` 消除 page/pageSize/total 样板。
+ *
+ * @param result - 后端返回的分页结果。
+ * @param map - 单条映射函数。
+ * @returns 条目被映射、分页元数据不变的新分页结果。
+ *
+ * @example
+ * list: async (params) => mapPaginated(await api.listUsers(params), toRow)
+ */
+export declare function mapPaginated<T, R>(result: PaginatedResult<T>, map: (item: T, index: number) => R): PaginatedResult<R>;
+/**
+ * 由声明式资源定义生成 `CrudPage` 所需的 `crud` 对象。
+ *
+ * @description 仅做字段筛选、列映射与默认值收集，不依赖 `@h-ai/kit`，可在纯 SPA 直接使用。
+ *
+ * @param resource - 资源定义（字段、标签、API）。
+ * @returns `CrudPage` 可直接消费的 `crud` 对象。
+ *
+ * @example
+ * const userCrud = defineCrud<User>({
+ *   name: 'user',
+ *   label: () => m.users_title(),
+ *   fields: [{ id: 'name', label: () => m.user_name(), type: 'text', filterable: true }],
+ *   api: { list: params => listUsers(params) },
+ * })
+ */
+export declare function defineCrud<T extends Record<string, unknown>>(resource: CrudResource<T>): CrudDef<T>;
+/**
+ * 在纯客户端（无 SvelteKit SSR）下为 `CrudPage` 创建数据 + 导航控制器。
+ *
+ * @description `CrudPage` 通过 `nav.navigate(url)` 把搜索/过滤/分页写进 URL query，再调用 `nav.refresh()`
+ *   触发列表刷新。本控制器把 query 解析回参数、调用 `crud.api.list` 更新本地 `data`，并把查询串回填地址栏，
+ *   不触发整页跳转（避免刷新与登录态丢失）。连续请求只允许最新一轮更新状态（seq + AbortSignal 双保险），
+ *   失败时保留已有数据并暴露错误供页面重试。
+ *
+ * @param crud - `defineCrud` 的返回值。
+ * @param options - 加载策略；默认立即加载、失败保留旧数据、回填地址栏。
+ * @returns 含响应式 `data`、`nav` 适配器与 `load` / `reload` 的控制器。
+ *
+ * @example
+ * const controller = createCrudController(userCrud)
+ * // <CrudPage crud={userCrud} data={controller.data} nav={controller.nav}
+ * //   loading={controller.loading} loaded={controller.loaded}
+ * //   error={controller.error} onRetry={controller.reload} />
+ */
+export declare function createCrudController<T extends Record<string, unknown>>(crud: CrudDef<T>, options?: CrudControllerOptions): CrudController<T>;

package/dist/components/scenes/crud/crud-controller.svelte.js

@@ -0,0 +1,265 @@
+/**
+ * @h-ai/ui — CRUD 控制器（SPA 数据 + 导航托管）
+ *
+ * 为 `CrudPage` 提供两个框架级适配器，业务应用无需在各自项目里重复实现：
+ *   1. `defineCrud`：由声明式资源定义生成 `CrudPage` 所需的 `crud` 对象（字段筛选、列映射、默认值），
+ *      不依赖 `@h-ai/kit`，纯 SPA / Tauri / Capacitor 均可直接使用。
+ *   2. `createCrudController`：在纯客户端（无 SvelteKit SSR）下托管 `CrudPage` 的 `data` 与 `nav`，
+ *      把 `CrudPage` 通过 URL query 同步的搜索/过滤/分页参数解析回本地状态并重新拉取列表。
+ *
+ * 控制器特性：latest-wins（seq + AbortSignal 双保险）、失败保留旧数据、惰性加载、并发去重、
+ * 查询串回填地址栏（保留 pathname 与 hash，不整页跳转）。
+ *
+ * @module crud-controller
+ */
+import { SvelteURLSearchParams } from 'svelte/reactivity';
+/**
+ * 解析可能是 i18n 函数的文本。
+ */
+function resolveText(text) {
+    return typeof text === 'function' ? text() : text;
+}
+/**
+ * 映射分页结果的 `items`，保留 total / page / pageSize。
+ *
+ * @description 标准 `PaginatedResult<T>` 适配器：业务页面只需转换条目本身，
+ *   无需重复搬运分页元数据，配合 `CrudApi.list` 消除 page/pageSize/total 样板。
+ *
+ * @param result - 后端返回的分页结果。
+ * @param map - 单条映射函数。
+ * @returns 条目被映射、分页元数据不变的新分页结果。
+ *
+ * @example
+ * list: async (params) => mapPaginated(await api.listUsers(params), toRow)
+ */
+export function mapPaginated(result, map) {
+    return {
+        items: result.items.map(map),
+        total: result.total,
+        page: result.page,
+        pageSize: result.pageSize,
+    };
+}
+/**
+ * 由声明式资源定义生成 `CrudPage` 所需的 `crud` 对象。
+ *
+ * @description 仅做字段筛选、列映射与默认值收集，不依赖 `@h-ai/kit`，可在纯 SPA 直接使用。
+ *
+ * @param resource - 资源定义（字段、标签、API）。
+ * @returns `CrudPage` 可直接消费的 `crud` 对象。
+ *
+ * @example
+ * const userCrud = defineCrud<User>({
+ *   name: 'user',
+ *   label: () => m.users_title(),
+ *   fields: [{ id: 'name', label: () => m.user_name(), type: 'text', filterable: true }],
+ *   api: { list: params => listUsers(params) },
+ * })
+ */
+export function defineCrud(resource) {
+    const fields = [...resource.fields].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+    return {
+        resource,
+        getListFields: () => fields.filter(f => f.inList !== false),
+        getFilterFields: () => fields.filter(f => f.filterable === true),
+        // readonly 仅表示“编辑态禁用”（由 CrudEditPanel 在 edit 模式 disable），新建仍可填写；
+        // 因此创建表单只按 inCreate 过滤，不排除 readonly 字段。
+        getCreateFields: () => fields.filter(f => f.inCreate !== false),
+        getEditFields: () => fields.filter(f => f.inEdit !== false),
+        getDetailFields: () => fields.filter(f => f.inDetail !== false),
+        toTableColumns: () => fields
+            .filter(f => f.inList !== false)
+            .map(f => ({
+            key: f.id,
+            label: resolveText(f.label),
+            width: f.width,
+            align: f.align,
+            render: f.render ? (item) => f.render(item[f.id], item) : undefined,
+        })),
+        getDefaultValues: () => Object.fromEntries(fields.filter(f => f.defaultValue !== undefined).map(f => [f.id, f.defaultValue])),
+        api: resource.api,
+    };
+}
+/**
+ * 在纯客户端（无 SvelteKit SSR）下为 `CrudPage` 创建数据 + 导航控制器。
+ *
+ * @description `CrudPage` 通过 `nav.navigate(url)` 把搜索/过滤/分页写进 URL query，再调用 `nav.refresh()`
+ *   触发列表刷新。本控制器把 query 解析回参数、调用 `crud.api.list` 更新本地 `data`，并把查询串回填地址栏，
+ *   不触发整页跳转（避免刷新与登录态丢失）。连续请求只允许最新一轮更新状态（seq + AbortSignal 双保险），
+ *   失败时保留已有数据并暴露错误供页面重试。
+ *
+ * @param crud - `defineCrud` 的返回值。
+ * @param options - 加载策略；默认立即加载、失败保留旧数据、回填地址栏。
+ * @returns 含响应式 `data`、`nav` 适配器与 `load` / `reload` 的控制器。
+ *
+ * @example
+ * const controller = createCrudController(userCrud)
+ * // <CrudPage crud={userCrud} data={controller.data} nav={controller.nav}
+ * //   loading={controller.loading} loaded={controller.loaded}
+ * //   error={controller.error} onRetry={controller.reload} />
+ */
+export function createCrudController(crud, options = {}) {
+    const defaultPageSize = crud.resource.defaultPageSize ?? 10;
+    const keepPreviousData = options.keepPreviousData !== false;
+    const syncUrl = options.syncUrl !== false;
+    const filterIds = crud.getFilterFields().map(f => f.id);
+    const data = $state({
+        items: [],
+        total: 0,
+        page: 1,
+        pageSize: defaultPageSize,
+        filters: {},
+    });
+    // 最近一次解析出的查询参数（供 refresh 使用）。
+    let pending = { search: '', page: 1, pageSize: defaultPageSize };
+    // 单调递增请求号；只有最新一轮请求可写回状态（latest-wins）。
+    let listRequestSeq = 0;
+    // 最新一轮请求的取消控制器；新请求发起前 abort 上一轮。
+    let abortController;
+    // 并发去重：同参数请求在途时复用同一 Promise。
+    let inFlightKey;
+    let inFlightPromise;
+    let loading = $state(false);
+    let loaded = $state(false);
+    let error = $state(undefined);
+    /** 生成参数的稳定 key（用于并发去重）。 */
+    function paramsKey(params) {
+        return JSON.stringify(Object.entries(params).sort(([a], [b]) => a.localeCompare(b)));
+    }
+    /** 把成功响应写回响应式 data，并回填 filters 供筛选栏回显。 */
+    function applyResult(result, params) {
+        data.items = result.items;
+        data.total = result.total;
+        data.page = result.page;
+        data.pageSize = result.pageSize;
+        const filters = { search: params.search ?? '' };
+        for (const id of filterIds) {
+            if (params[id] !== undefined)
+                filters[id] = params[id];
+        }
+        data.filters = filters;
+    }
+    /**
+     * 按参数拉取列表并写回响应式 data。
+     *
+     * @description 暴露查询中、已成功加载和错误三种状态；连续请求只允许最新响应更新状态与数据，
+     *   旧请求被 abort 且其结果被丢弃；失败时按 keepPreviousData 决定是否保留旧列表。
+     *
+     * @param params - 搜索、过滤与分页参数。
+     * @returns 最新请求结算后完成；错误被保存在控制器中，避免未处理 Promise 拒绝。
+     */
+    function fetchList(params) {
+        const key = paramsKey(params);
+        // 并发去重：同参数请求在途时直接复用，避免重复打后端。
+        if (inFlightPromise && inFlightKey === key)
+            return inFlightPromise;
+        const requestSeq = ++listRequestSeq;
+        // 取消上一轮在途请求，实现 latest-wins 的第一重保险。
+        abortController?.abort();
+        const ac = new AbortController();
+        abortController = ac;
+        loading = true;
+        error = undefined;
+        // 不保留旧数据时立即清空，展示查询中占位；保留时维持旧列表避免闪烁。
+        if (!keepPreviousData) {
+            data.items = [];
+            data.total = 0;
+        }
+        inFlightKey = key;
+        const promise = (async () => {
+            try {
+                const result = await crud.api.list(params, { signal: ac.signal });
+                // 旧请求晚返回：seq 已被新请求覆盖时丢弃，绝不污染用户当前看到的结果。
+                if (requestSeq !== listRequestSeq)
+                    return;
+                applyResult(result, params);
+                loaded = true;
+            }
+            catch (cause) {
+                // 被新请求取代而 abort 的旧请求：静默丢弃，不写错误。
+                if (ac.signal.aborted || (cause instanceof Error && cause.name === 'AbortError'))
+                    return;
+                // 列表加载失败（慢响应/重启/超时）时保留上一次结果，绝不用空列表覆盖，避免误显示“0 条记录”；
+                // 同时暴露错误给页面：首次失败不能被当成一次成功的空结果。
+                if (requestSeq === listRequestSeq)
+                    error = cause instanceof Error ? cause : new Error(String(cause));
+            }
+            finally {
+                if (requestSeq === listRequestSeq) {
+                    loading = false;
+                    inFlightPromise = undefined;
+                    inFlightKey = undefined;
+                    abortController = undefined;
+                }
+            }
+        })();
+        inFlightPromise = promise;
+        return promise;
+    }
+    /** 从 CrudPage 生成的 URL 中解析查询参数。 */
+    function parseParams(url) {
+        const qs = url.includes('?') ? url.slice(url.indexOf('?') + 1) : '';
+        const sp = new SvelteURLSearchParams(qs);
+        const params = {
+            search: sp.get('search') ?? '',
+            page: sp.get('page') ? Number(sp.get('page')) : 1,
+            pageSize: sp.get('pageSize') ? Number(sp.get('pageSize')) : defaultPageSize,
+        };
+        for (const key of ['sortBy', 'sortDirection']) {
+            const v = sp.get(key);
+            if (v !== null && v !== '')
+                params[key] = v;
+        }
+        for (const id of filterIds) {
+            const v = sp.get(id);
+            if (v !== null && v !== '')
+                params[id] = v;
+        }
+        return params;
+    }
+    /** 把查询串回填地址栏，保留 pathname 与 hash，不触发跳转；SSR / 无 history 环境静默跳过。 */
+    function writeUrl(url) {
+        if (!syncUrl)
+            return;
+        const his = globalThis.history;
+        const loc = globalThis.location;
+        if (!his?.replaceState || !loc)
+            return;
+        const qs = url.includes('?') ? url.slice(url.indexOf('?')) : '';
+        try {
+            his.replaceState(his.state, '', `${loc.pathname}${qs}${loc.hash}`);
+        }
+        catch {
+            // 隐私模式 / 跨域等限制下忽略，不影响数据加载。
+        }
+    }
+    const nav = {
+        pathname: '',
+        navigate: (url) => {
+            // 仅解析参数并回填地址栏，不做真实跳转。
+            pending = parseParams(url);
+            writeUrl(url);
+        },
+        refresh: () => fetchList(pending),
+    };
+    // 默认立即加载；惰性页签显式关闭，避免挂载时抢占后端资源，在首次激活时调用 load()。
+    if (options.autoLoad !== false)
+        void fetchList(pending);
+    return {
+        get data() {
+            return data;
+        },
+        nav,
+        load: () => fetchList(pending),
+        reload: () => fetchList(pending),
+        get loading() {
+            return loading;
+        },
+        get loaded() {
+            return loaded;
+        },
+        get error() {
+            return error;
+        },
+    };
+}

package/dist/components/scenes/crud/index.d.ts

@@ -1,9 +1,13 @@
 /**
  * @h-ai/ui — CRUD 场景组件
  *
- * 提供声明式 CRUD 页面组件，基于 kit.crud.define() 定义自动渲染列表、搜索过滤、分页、详情/编辑面板和删除确认。
+ * 提供声明式 CRUD 页面组件与框架级控制器：
+ * - `CrudPage` 组件：自动渲染列表、搜索过滤、分页、详情/编辑面板、删除确认，以及查询中/失败/空态。
+ * - `defineCrud` / `createCrudController`：纯客户端（无 SvelteKit SSR）下托管数据与导航，
+ *   业务应用无需自建 CRUD 适配层。
  * @module crud
  */
+export * from './crud-controller.svelte.js';
 export type * from './crud-types.js';
 export { default as CrudDeleteConfirm } from './CrudDeleteConfirm.svelte';
 export { default as CrudDetailPanel } from './CrudDetailPanel.svelte';

package/dist/components/scenes/crud/index.js

@@ -1,9 +1,13 @@
 /**
  * @h-ai/ui — CRUD 场景组件
  *
- * 提供声明式 CRUD 页面组件，基于 kit.crud.define() 定义自动渲染列表、搜索过滤、分页、详情/编辑面板和删除确认。
+ * 提供声明式 CRUD 页面组件与框架级控制器：
+ * - `CrudPage` 组件：自动渲染列表、搜索过滤、分页、详情/编辑面板、删除确认，以及查询中/失败/空态。
+ * - `defineCrud` / `createCrudController`：纯客户端（无 SvelteKit SSR）下托管数据与导航，
+ *   业务应用无需自建 CRUD 适配层。
  * @module crud
  */
+export * from './crud-controller.svelte.js';
 export { default as CrudDeleteConfirm } from './CrudDeleteConfirm.svelte';
 export { default as CrudDetailPanel } from './CrudDetailPanel.svelte';
 export { default as CrudEditPanel } from './CrudEditPanel.svelte';

package/dist/messages/en-US.json

@@ -262,12 +262,14 @@
   "crud_edit": "Edit",
   "crud_detail": "Detail",
   "crud_delete": "Delete",
+  "crud_load_failed": "Failed to load",
+  "crud_retry": "Retry",
   "crud_save": "Save",
   "crud_cancel": "Cancel",
   "crud_close": "Close",
   "crud_search_placeholder": "Search...",
   "crud_no_data": "No data",
-  "crud_loading": "Loading...",
+  "crud_loading": "Querying…",
   "crud_delete_title": "Confirm Delete",
   "crud_delete_message": "Are you sure you want to delete this record? This action cannot be undone.",
   "crud_submit_success": "Operation successful",

package/dist/messages/zh-CN.json

@@ -262,12 +262,14 @@
   "crud_edit": "编辑",
   "crud_detail": "详情",
   "crud_delete": "删除",
+  "crud_load_failed": "加载失败",
+  "crud_retry": "重试",
   "crud_save": "保存",
   "crud_cancel": "取消",
   "crud_close": "关闭",
   "crud_search_placeholder": "搜索...",
   "crud_no_data": "暂无数据",
-  "crud_loading": "加载中...",
+  "crud_loading": "查询中…",
   "crud_delete_title": "确认删除",
   "crud_delete_message": "确定要删除此记录吗？此操作不可恢复。",
   "crud_submit_success": "操作成功",

package/dist/toast.svelte.d.ts

@@ -42,4 +42,50 @@ declare class ToastState {
  * Toast 单例
  */
 export declare const toast: ToastState;
+/**
+ * 弹出操作成功提示（右上角）。
+ *
+ * @description 统一封装 toast 单例，业务应用无需自建 toast 工具文件即可获得一致的成功反馈。
+ *
+ * @param message - 用户可见的成功文案（已本地化）。
+ * @param duration - 可选停留时长（毫秒），默认 3000。
+ *
+ * @example
+ * notifySuccess(m.submit_submitted())
+ */
+export declare function notifySuccess(message: string, duration?: number): string;
+/**
+ * 弹出操作失败提示（右上角）。
+ *
+ * @description 接受 `Error` 或字符串；`Error` 取其 message，其余回退到 fallback，
+ *   避免各业务页面重复实现错误文案兜底逻辑。
+ *
+ * @param error - 错误对象或已本地化的错误文案。
+ * @param fallback - 当 error 非 Error 且为空时使用的兜底文案。
+ * @param duration - 可选停留时长（毫秒），默认 5000。
+ *
+ * @example
+ * notifyError(error, m.submit_failed())
+ */
+export declare function notifyError(error: unknown, fallback?: string, duration?: number): string;
+/**
+ * 弹出信息提示（右上角）。
+ *
+ * @param message - 用户可见文案（已本地化）。
+ * @param duration - 可选停留时长（毫秒），默认 3000。
+ *
+ * @example
+ * notifyInfo(m.common_saved())
+ */
+export declare function notifyInfo(message: string, duration?: number): string;
+/**
+ * 弹出警告提示（右上角）。
+ *
+ * @param message - 用户可见文案（已本地化）。
+ * @param duration - 可选停留时长（毫秒），默认 5000。
+ *
+ * @example
+ * notifyWarning(m.quota_almost_reached())
+ */
+export declare function notifyWarning(message: string, duration?: number): string;
 export {};

package/dist/toast.svelte.js

@@ -75,3 +75,64 @@ class ToastState {
  * Toast 单例
  */
 export const toast = new ToastState();
+/** 成功提示默认停留时长（毫秒）。 */
+const SUCCESS_DURATION = 3000;
+/** 失败提示默认停留时长（毫秒），比成功略长便于阅读错误信息。 */
+const ERROR_DURATION = 5000;
+/**
+ * 弹出操作成功提示（右上角）。
+ *
+ * @description 统一封装 toast 单例，业务应用无需自建 toast 工具文件即可获得一致的成功反馈。
+ *
+ * @param message - 用户可见的成功文案（已本地化）。
+ * @param duration - 可选停留时长（毫秒），默认 3000。
+ *
+ * @example
+ * notifySuccess(m.submit_submitted())
+ */
+export function notifySuccess(message, duration = SUCCESS_DURATION) {
+    return toast.success(message, duration);
+}
+/**
+ * 弹出操作失败提示（右上角）。
+ *
+ * @description 接受 `Error` 或字符串；`Error` 取其 message，其余回退到 fallback，
+ *   避免各业务页面重复实现错误文案兜底逻辑。
+ *
+ * @param error - 错误对象或已本地化的错误文案。
+ * @param fallback - 当 error 非 Error 且为空时使用的兜底文案。
+ * @param duration - 可选停留时长（毫秒），默认 5000。
+ *
+ * @example
+ * notifyError(error, m.submit_failed())
+ */
+export function notifyError(error, fallback = '', duration = ERROR_DURATION) {
+    const message = error instanceof Error
+        ? error.message
+        : (typeof error === 'string' ? error : fallback);
+    return toast.error(message || fallback, duration);
+}
+/**
+ * 弹出信息提示（右上角）。
+ *
+ * @param message - 用户可见文案（已本地化）。
+ * @param duration - 可选停留时长（毫秒），默认 3000。
+ *
+ * @example
+ * notifyInfo(m.common_saved())
+ */
+export function notifyInfo(message, duration = SUCCESS_DURATION) {
+    return toast.info(message, duration);
+}
+/**
+ * 弹出警告提示（右上角）。
+ *
+ * @param message - 用户可见文案（已本地化）。
+ * @param duration - 可选停留时长（毫秒），默认 5000。
+ *
+ * @example
+ * notifyWarning(m.quota_almost_reached())
+ */
+export function notifyWarning(message, duration = ERROR_DURATION) {
+    return toast.warning(message, duration);
+}

package/dist/types.d.ts

@@ -671,6 +671,18 @@ export interface TabItem {
     /** 图标 */
     icon?: string;
 }
+/**
+ * 标签页内容上下文
+ *
+ * 传给 `Tabs` 的 `children` 插槽，支持惰性挂载：只渲染已激活过的页签内容，
+ * 不预加载不可见页签。
+ */
+export interface TabsContentContext {
+    /** 当前激活的标签 key */
+    active: string;
+    /** 指定标签是否已被激活过（`lazy` 为 false 时恒为 true） */
+    isActivated: (key: string) => boolean;
+}
 /**
  * 标签页属性
  */
@@ -687,8 +699,12 @@ export interface TabsProps extends DataAttributes {
     class?: string;
     /** 变化事件 */
     onchange?: (key: string) => void;
-    /** 内容插槽 */
-    children?: Snippet;
+    /** 页签首次激活时触发一次；用于惰性加载对应内容（如调用控制器的 load） */
+    onactivate?: (key: string) => void;
+    /** 是否惰性挂载页签内容：为 true 时未激活过的页签不渲染，`isActivated` 据此判断 */
+    lazy?: boolean;
+    /** 内容插槽；参数提供当前激活项与惰性挂载判断 */
+    children?: Snippet<[TabsContentContext]>;
 }
 /**
  * 头像属性

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.49",
+  "version": "0.1.0-alpha.50",
   "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.49"
+    "@h-ai/core": "0.1.0-alpha.50"
   },
   "devDependencies": {
     "@sveltejs/package": "^2.5.7",