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

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)
   // ─── 状态 ───
 
   /** 表格行的主键字段。 */
@@ -655,7 +690,7 @@
   {/if}
 
   <!-- 搜索 + 过滤栏 -->
-  {#if searchable || filterFields.length > 0}
+  {#if searchable || filterFields.length > 0 || toolbarLeading || toolbarActions}
     {#if toolbarStyle === 'toolbar'}
       <TableToolbar
         {searchable}
@@ -697,101 +732,143 @@
 
   <!-- 数据列表 -->
   <Card padding='none' class={listCardClass}>
-    {#if card}
-      <!-- 卡片视图使用独立滚动容器，分页栏始终保留在容器外。 -->
-      <div class='min-h-0 flex-1 overflow-auto'>
-        {#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>;