@h-ai/ui 0.1.0-alpha.40 → 0.1.0-alpha.41

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

@@ -1,17 +1,28 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../../types.js';
-import type { CrudDensity, CrudFormConfig, CrudPaginationConfig } from './crud-types.js';
+import type { CrudDensity, CrudFormConfig, CrudPaginationConfig, CrudToolbarStyle } from './crud-types.js';
 import type { NavAdapter } from './nav-adapter.js';
+/** CRUD 字段定义，决定列表、筛选器和表单的字段行为。 */
 type FieldDef = {
+    /** 字段稳定标识，同时对应数据记录中的属性名。 */
     id: string;
+    /** 字段显示文案，允许通过函数延迟读取当前语言。 */
     label: string | (() => string);
+    /** 字段控件类型，最终由表单或筛选器解释。 */
     type: string;
+    /** 是否出现在列表中；未设置时默认显示。 */
     inList?: boolean;
+    /** 是否出现在筛选器中；只有显式为 true 时显示。 */
     filterable?: boolean;
+    /** 编辑时是否禁止修改。 */
     readonly?: boolean;
+    /** 是否出现在新建表单中；未设置时默认显示。 */
     inCreate?: boolean;
+    /** 是否出现在编辑表单中；未设置时默认显示。 */
     inEdit?: boolean;
+    /** 是否出现在详情面板中；未设置时默认显示。 */
     inDetail?: boolean;
+    /** 选择类字段的静态选项或动态选项工厂。 */
     options?: Array<{
         label: string;
         value: string | number | boolean;
@@ -19,6 +30,7 @@ type FieldDef = {
         label: string;
         value: string | number | boolean;
     }>);
+    /** 表单校验规则。 */
     validation?: {
         required?: boolean;
         min?: number;
@@ -26,41 +38,73 @@ type FieldDef = {
         pattern?: string;
         message?: string;
     };
+    /** 列宽 CSS 值。 */
     width?: string;
+    /** 单元格对齐方式。 */
     align?: 'left' | 'center' | 'right';
+    /** 列表单元格的自定义渲染函数。 */
     render?: (value: unknown, item: Record<string, unknown>) => string;
+    /** 输入控件占位文案。 */
     placeholder?: string | (() => string);
+    /** 日期范围起始值 key。 */
+    startKey?: string;
+    /** 日期范围结束值 key。 */
+    endKey?: string;
+    /** 新建记录时使用的默认值。 */
     defaultValue?: unknown;
+    /** 字段排序权重，数值越小越靠前。 */
     order?: number;
 };
+/** CrudPage 使用的异步资源操作集合。 */
 type CrudApi = {
+    /** 获取当前分页、筛选和排序结果。 */
     list(params: Record<string, unknown>): Promise<{
         items: Record<string, unknown>[];
         total: number;
         page: number;
         pageSize: number;
     }>;
+    /** 按主键获取一条记录。 */
     get?(id: string): Promise<Record<string, unknown> | null>;
+    /** 创建一条记录。 */
     create?(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** 更新一条记录。 */
     update?(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** 删除一条记录。 */
     remove?(id: string): Promise<void>;
 };
+/** 声明式 CRUD 资源及字段转换能力。 */
 type CrudDef = {
+    /** 资源元信息与后端 API。 */
     resource: {
+        /** 资源名称，用于识别当前业务实体。 */
         name: string;
+        /** 资源标题文案。 */
         label: string | (() => string);
+        /** 记录主键字段，默认使用 id。 */
         keyField?: string;
+        /** 资源字段定义。 */
         fields: FieldDef[];
+        /** 默认分页条数。 */
         defaultPageSize?: number;
+        /** 是否显示搜索框。 */
         searchable?: boolean;
+        /** 搜索框占位文案。 */
         searchPlaceholder?: string | (() => string);
+        /** 资源 CRUD API。 */
         api: CrudApi;
     };
+    /** 获取列表字段。 */
     getListFields: () => FieldDef[];
+    /** 获取筛选字段。 */
     getFilterFields: () => FieldDef[];
+    /** 获取新建字段。 */
     getCreateFields: () => FieldDef[];
+    /** 获取编辑字段。 */
     getEditFields: () => FieldDef[];
+    /** 获取详情字段。 */
     getDetailFields: () => FieldDef[];
+    /** 转换为 DataTable 列定义。 */
     toTableColumns: () => Array<{
         key: string;
         label: string;
@@ -68,11 +112,15 @@ type CrudDef = {
         align?: string;
         render?: (item: Record<string, unknown>) => string;
     }>;
+    /** 生成新建表单默认值。 */
     getDefaultValues: () => Record<string, unknown>;
+    /** API 操作代理。 */
     api: CrudApi;
 };
 type $$ComponentProps = {
+    /** CRUD 资源定义及其 API 操作。 */
     crud: CrudDef;
+    /** 当前页数据与服务端分页元数据。 */
     data: {
         items: Record<string, unknown>[];
         total: number;
@@ -80,23 +128,56 @@ type $$ComponentProps = {
         pageSize: number;
         filters?: Record<string, unknown>;
     };
+    /** 新建、编辑、删除权限；未设置的权限默认跟随 API 是否存在。 */
     permissions?: {
         create?: boolean;
         update?: boolean;
         delete?: boolean;
     };
+    /** 新建/编辑面板展示配置。 */
     form?: CrudFormConfig;
+    /** 分页栏展示配置。 */
     pagination?: CrudPaginationConfig;
+    /** 列表密度，影响行高、操作按钮和面板控件尺寸。 */
     density?: CrudDensity;
+    /** 点击详情图标是否打开详情面板。 */
     rowClickDetail?: boolean;
+    /** 是否显示默认页面标题栏；使用 toolbarLeading 承载标题时可设为 false。 */
+    showHeader?: boolean;
+    /** 每行额外操作按钮插槽。 */
     listItemActions?: Snippet<[Record<string, unknown>]>;
+    /** 自定义表格单元格；参数依次为行记录和列 key。 */
+    tableCell?: Snippet<[Record<string, unknown>, string]>;
+    /** 点击表格行时的回调。 */
+    onrowclick?: (item: Record<string, unknown>) => void;
+    /** 编辑表单额外字段插槽。 */
     editFormExtra?: Snippet<[Record<string, unknown> | null, 'create' | 'edit']>;
+    /** 详情面板额外内容插槽。 */
     detailExtra?: Snippet<[Record<string, unknown>]>;
+    /** 页面标题右侧额外操作插槽。 */
     headerActions?: Snippet;
+    /** 工具栏风格：`toolbar` 使用图标弹层工具栏（默认），`filter-bar` 使用平铺筛选栏。 */
+    toolbarStyle?: CrudToolbarStyle;
+    /** toolbar 风格下工具栏左侧内容插槽，可用于放置页面标题或说明。 */
+    toolbarLeading?: Snippet;
+    /** TableToolbar 风格下工具栏右侧自定义操作插槽。 */
+    toolbarActions?: Snippet;
+    /** 卡片列表项渲染插槽；存在时替代 DataTable，仍复用工具栏、分页和独立滚动容器。 */
+    card?: Snippet<[Record<string, unknown>]>;
+    /** 可排序列配置；为空时默认使用全部列表列。 */
+    sortableColumns?: Array<{
+        key: string;
+        label: string;
+    }>;
+    /** 删除前钩子，返回 false 时取消删除。 */
     onbeforedelete?: (item: Record<string, unknown>) => Promise<boolean> | boolean;
+    /** 新建或编辑成功后的回调。 */
     onaftersubmit?: (item: Record<string, unknown>, mode: 'create' | 'edit') => void;
+    /** 删除成功后的回调。 */
     onafterdelete?: (item: Record<string, unknown>) => void;
+    /** 自定义错误回调。 */
     onerror?: (error: string) => void;
+    /** 列表路由基础路径。 */
     basePath?: string;
     /**
      * 路由适配器：用于读取当前 pathname、同步过滤参数到 URL、列表刷新。
@@ -105,6 +186,7 @@ type $$ComponentProps = {
      * 以获得客户端跳转 + invalidateAll 体验。
      */
     nav?: NavAdapter;
+    /** 根节点自定义 class。 */
     class?: string;
 } & DataAttributes;
 /**

package/dist/components/scenes/crud/crud-types.d.ts

@@ -49,6 +49,8 @@ export interface CrudPaginationConfig {
     /** 是否显示首页 / 末页跳转按钮（默认 true；紧凑视图可仅保留上一页 / 下一页） */
     showFirstLast?: boolean;
 }
+/** CrudPage 工具栏风格；toolbar 是默认的图标弹层布局。 */
+export type CrudToolbarStyle = 'filter-bar' | 'toolbar';
 /** CrudPage 初始列表数据（由 +page.server.ts load 返回） */
 export interface CrudPageData<T = Record<string, unknown>> {
     items: T[];
@@ -93,6 +95,10 @@ export interface CrudPageProps<T = Record<string, unknown>> extends DataAttribut
                 align?: 'left' | 'center' | 'right';
                 render?: (value: unknown, item: Record<string, unknown>) => string;
                 placeholder?: string | (() => string);
+                /** 日期范围起始值 key；默认 `${id}Start`。 */
+                startKey?: string;
+                /** 日期范围结束值 key；默认 `${id}End`。 */
+                endKey?: string;
                 defaultValue?: unknown;
                 order?: number;
             }>;
@@ -150,14 +156,33 @@ export interface CrudPageProps<T = Record<string, unknown>> extends DataAttribut
     density?: CrudDensity;
     /** 列表行点击是否打开详情（默认 true） */
     rowClickDetail?: boolean;
+    /** 是否显示默认页面标题栏；需要把标题放进工具栏左侧时设为 false。 */
+    showHeader?: boolean;
     /** 列表行操作按钮插槽 */
     listItemActions?: Snippet<[T]>;
+    /** 自定义表格单元格插槽；参数依次为行记录和列 key。 */
+    tableCell?: Snippet<[T, string]>;
+    /** 点击表格行的回调。 */
+    onrowclick?: (item: T) => void;
     /** 编辑表单额外字段插槽 */
     editFormExtra?: Snippet<[T | null, 'create' | 'edit']>;
     /** 详情额外内容插槽 */
     detailExtra?: Snippet<[T]>;
     /** 页面头部额外操作区插槽 */
     headerActions?: Snippet;
+    /** 工具栏风格；toolbar 使用图标弹层，filter-bar 使用平铺筛选栏。 */
+    toolbarStyle?: CrudToolbarStyle;
+    /** toolbar 风格下工具栏左侧内容插槽，可放置页面标题或说明。 */
+    toolbarLeading?: Snippet;
+    /** 工具栏右侧自定义操作插槽。 */
+    toolbarActions?: Snippet;
+    /** 卡片列表项渲染插槽；存在时替代数据表格，分页和滚动容器保持一致。 */
+    card?: Snippet<[T]>;
+    /** 可排序列；为空时默认使用全部列表列。 */
+    sortableColumns?: Array<{
+        key: string;
+        label: string;
+    }>;
     /** 删除前钩子（返回 false 取消） */
     onbeforedelete?: (item: T) => Promise<boolean> | boolean;
     /** 提交成功后钩子 */

package/dist/messages/en-US.json

@@ -283,6 +283,23 @@
   "crud_total": "{count} items total",
   "crud_detail_empty": "-",
   "crud_field_required": "This field is required",
+  "toolbar_search": "Search",
+  "toolbar_filter": "Filter",
+  "toolbar_filter_conditions": "Filter conditions",
+  "toolbar_filter_reset": "Reset",
+  "toolbar_filter_all": "All",
+  "toolbar_sort": "Sort",
+  "toolbar_sort_conditions": "Sort conditions",
+  "toolbar_sort_default": "Default sort",
+  "toolbar_sort_field": "Sort field",
+  "toolbar_sort_default_order": "Default order",
+  "toolbar_sort_direction": "Sort direction",
+  "toolbar_sort_desc": "Descending",
+  "toolbar_sort_asc": "Ascending",
+  "toolbar_sort_summary": "Sorted by {label} {direction}",
+  "toolbar_view_switch": "View switch",
+  "toolbar_view_table": "Table view",
+  "toolbar_view_card": "Card view",
   "error_go_back": "Go Back",
   "error_back_home": "Back to Home",
   "error_401_title": "Unauthorized",

package/dist/messages/zh-CN.json

@@ -283,6 +283,23 @@
   "crud_total": "共 {count} 条",
   "crud_detail_empty": "-",
   "crud_field_required": "此字段为必填项",
+  "toolbar_search": "搜索",
+  "toolbar_filter": "筛选",
+  "toolbar_filter_conditions": "筛选条件",
+  "toolbar_filter_reset": "重置",
+  "toolbar_filter_all": "全部",
+  "toolbar_sort": "排序",
+  "toolbar_sort_conditions": "排序条件",
+  "toolbar_sort_default": "默认排序",
+  "toolbar_sort_field": "排序字段",
+  "toolbar_sort_default_order": "默认排序",
+  "toolbar_sort_direction": "排序方向",
+  "toolbar_sort_desc": "降序",
+  "toolbar_sort_asc": "升序",
+  "toolbar_sort_summary": "按 {label} {direction} 排列",
+  "toolbar_view_switch": "视图切换",
+  "toolbar_view_table": "表格视图",
+  "toolbar_view_card": "卡片视图",
   "error_go_back": "返回上一页",
   "error_back_home": "返回首页",
   "error_401_title": "未授权访问",

package/package.json

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