@h-ai/ui 0.1.0-alpha.67 → 0.1.0-alpha.68

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

@@ -4,6 +4,16 @@
 
   使用 Svelte 5 Runes ($props, $state, $derived)
   使用 compounds/primitives 组件：Drawer, Modal, FormField, Input, Select, Textarea, Checkbox, Button
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { CrudEditPanel } from '@h-ai/ui'
+  const props: ComponentProps<typeof CrudEditPanel> = { open: true, mode: 'edit', title: '编辑用户', fields: [{ id: 'email', label: '邮箱', type: 'email' }], formData: { email: 'ada@example.com' } }
+  const component = mount(CrudEditPanel, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'

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

@@ -31,6 +31,16 @@ type $$ComponentProps = {
  *
  * 使用 Svelte 5 Runes ($props, $state, $derived)
  * 使用 compounds/primitives 组件：Drawer, Modal, FormField, Input, Select, Textarea, Checkbox, Button
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { CrudEditPanel } from '@h-ai/ui'
+ * const props: ComponentProps<typeof CrudEditPanel> = { open: true, mode: 'edit', title: '编辑用户', fields: [{ id: 'email', label: '邮箱', type: 'email' }], formData: { email: 'ada@example.com' } }
+ * const component = mount(CrudEditPanel, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const CrudEditPanel: import("svelte").Component<$$ComponentProps, {}, "open" | "formData">;
 type CrudEditPanel = ReturnType<typeof CrudEditPanel>;

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

@@ -3,6 +3,16 @@
   CRUD 搜索 + 过滤栏组件
 
   使用 Svelte 5 Runes ($props, $state)
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { CrudFilterBar } from '@h-ai/ui'
+  const props: ComponentProps<typeof CrudFilterBar> = { searchable: true, filterFields: [{ id: 'active', label: '状态', type: 'boolean' }], filterValues: { active: true } }
+  const component = mount(CrudFilterBar, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
@@ -12,6 +22,14 @@
   import Input from '../../primitives/Input.svelte'
   import Select from '../../primitives/Select.svelte'
 
+  /**
+   * 工具栏过滤字段的局部视图；值由宿主条件查询消费。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: FilterFieldDef = { id: 'active', label: '状态', type: 'boolean' }
+   * ```
+   */
   type FilterFieldDef = {
     id: string
     label: string | (() => string)

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

@@ -1,4 +1,12 @@
 import type { DataAttributes } from '../../../types.js';
+/**
+ * 工具栏过滤字段的局部视图；值由宿主条件查询消费。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FilterFieldDef = { id: 'active', label: '状态', type: 'boolean' }
+ * ```
+ */
 type FilterFieldDef = {
     id: string;
     label: string | (() => string);
@@ -33,6 +41,16 @@ type $$ComponentProps = {
  * CRUD 搜索 + 过滤栏组件
  *
  * 使用 Svelte 5 Runes ($props, $state)
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { CrudFilterBar } from '@h-ai/ui'
+ * const props: ComponentProps<typeof CrudFilterBar> = { searchable: true, filterFields: [{ id: 'active', label: '状态', type: 'boolean' }], filterValues: { active: true } }
+ * const component = mount(CrudFilterBar, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const CrudFilterBar: import("svelte").Component<$$ComponentProps, {}, "searchValue" | "filterValues">;
 type CrudFilterBar = ReturnType<typeof CrudFilterBar>;

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

@@ -8,7 +8,15 @@
   使用 compounds 组件：Card, DataTable, PageHeader, Pagination, Drawer, Modal
 
   @example
-  <CrudPage crud={userCrud} data={data} permissions={{ create: true, update: true, delete: true }} />
+  ```svelte
+  <script lang="ts">
+    import { CrudPage, defineCrud } from '@h-ai/ui'
+    import type { CrudPageProps } from '@h-ai/ui'
+    const crud = defineCrud({ name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } })
+    const props: CrudPageProps = { crud, data: { items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }, permissions: { create: true, update: true, delete: false } }
+  </script>
+  <CrudPage {...props} />
+  ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'
@@ -34,11 +42,27 @@
 
   // ─── 类型定义 ───
 
+  /**
+   * 详情/列表对字段定义的局部视图，不是独立的公开资源模型。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: FieldDef = { id: 'email', label: '邮箱', type: 'email', inDetail: true }
+   * ```
+   */
   type FieldDef = CrudFieldDef
 
   // 使用 method shorthand 语法（双向协变）以兼容来自 @h-ai/kit 的 CrudOperations 类型
   // 详见：https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-6.html#strict-function-types
-  /** CrudPage 使用的异步资源操作集合。 */
+  /**
+   * CrudPage 使用的异步资源操作集合。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const api: CrudApi = { list: async () => ({ items: [{ id: 'u1' }], total: 1, page: 1, pageSize: 20 }) }
+   * const page = await api.list({ page: 1 })
+   * ```
+   */
   type CrudApi = {
     /** 获取当前分页、筛选和排序结果。 */
     list(params: Record<string, unknown>): Promise<{ items: Record<string, unknown>[], total: number, page: number, pageSize: number }>
@@ -52,7 +76,15 @@
     remove?(id: string): Promise<void>
   }
 
-  /** 声明式 CRUD 资源及字段转换能力。 */
+  /**
+   * 声明式 CRUD 资源及字段转换能力。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const definition: CrudDef = crud
+   * const fields = definition.getListFields()
+   * ```
+   */
   type CrudDef = {
     /** 资源元信息与后端 API。 */
     resource: {
@@ -238,7 +270,7 @@
   /** 是否使用紧凑列表密度。 */
   const isCompact = $derived(density === 'compact')
   /** 页面主体垂直间距；列表卡片会占满其余可用高度。 */
-  const pageGapClass = 'flex min-h-0 h-full flex-col gap-5'
+  const pageGapClass = 'flex min-h-0 h-full min-w-0 flex-1 flex-col gap-5'
   /** 行内操作按钮尺寸。 */
   const actionButtonSize = $derived(isCompact ? 'xs' : 'sm')
   /** 行内操作图标尺寸。 */
@@ -255,7 +287,7 @@
       : 'flex min-h-0 flex-1 flex-col overflow-hidden rounded-[1.25rem] border-base-content/7 shadow-sm [&>.card-body]:min-h-0 [&>.card-body]:flex-1',
   )
   /** 分页栏样式；shrink-0 保证它始终贴在卡片底部。 */
-  const paginationBarClass = 'shrink-0 border-t border-base-content/5 px-4 py-3'
+  const paginationBarClass = 'mt-auto shrink-0 border-t border-base-content/5 px-4 py-3'
 
   // 表单展示配置（抽屉 / 弹窗）
   /** 编辑/新建面板类型。 */

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

@@ -3,8 +3,24 @@ import type { DataAttributes } from '../../../types.js';
 import type { CrudFieldDef } from './crud-controller.svelte.js';
 import type { CrudDensity, CrudFormConfig, CrudPaginationConfig, CrudToolbarStyle } from './crud-types.js';
 import type { NavAdapter } from './nav-adapter.js';
+/**
+ * 详情/列表对字段定义的局部视图，不是独立的公开资源模型。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FieldDef = { id: 'email', label: '邮箱', type: 'email', inDetail: true }
+ * ```
+ */
 type FieldDef = CrudFieldDef;
-/** CrudPage 使用的异步资源操作集合。 */
+/**
+ * CrudPage 使用的异步资源操作集合。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const api: CrudApi = { list: async () => ({ items: [{ id: 'u1' }], total: 1, page: 1, pageSize: 20 }) }
+ * const page = await api.list({ page: 1 })
+ * ```
+ */
 type CrudApi = {
     /** 获取当前分页、筛选和排序结果。 */
     list(params: Record<string, unknown>): Promise<{
@@ -22,7 +38,15 @@ type CrudApi = {
     /** 删除一条记录。 */
     remove?(id: string): Promise<void>;
 };
-/** 声明式 CRUD 资源及字段转换能力。 */
+/**
+ * 声明式 CRUD 资源及字段转换能力。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const definition: CrudDef = crud
+ * const fields = definition.getListFields()
+ * ```
+ */
 type CrudDef = {
     /** 资源元信息与后端 API。 */
     resource: {
@@ -163,7 +187,15 @@ type $$ComponentProps = {
  * 使用 compounds 组件：Card, DataTable, PageHeader, Pagination, Drawer, Modal
  *
  * @example
- * <CrudPage crud={userCrud} data={data} permissions={{ create: true, update: true, delete: true }} />
+ * ```svelte
+ * <script lang="ts">
+ *   import { CrudPage, defineCrud } from '@h-ai/ui'
+ *   import type { CrudPageProps } from '@h-ai/ui'
+ *   const crud = defineCrud({ name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } })
+ *   const props: CrudPageProps = { crud, data: { items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }, permissions: { create: true, update: true, delete: false } }
+ * </script>
+ * <CrudPage {...props} />
+ * ```
  */
 declare const CrudPage: import("svelte").Component<$$ComponentProps, {}, "">;
 type CrudPage = ReturnType<typeof CrudPage>;

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

@@ -15,16 +15,48 @@
 import type { PaginatedResult } from '@h-ai/core';
 import type { FormColSpan } from '../../../types.js';
 import type { NavAdapter } from './nav-adapter.js';
-/** 字段展示形式；与 `CrudEditPanel` / `CrudFilterBar` 支持的类型对齐，保留 `string` 以兼容 `@h-ai/kit`。 */
+/**
+ * 字段展示形式；与 `CrudEditPanel` / `CrudFilterBar` 支持的类型对齐，保留 `string` 以兼容 `@h-ai/kit`。
+ *
+ * @example
+ * ```ts
+ * import type { CrudFieldType } from '@h-ai/ui'
+ * const example: CrudFieldType = 'email'
+ * ```
+ */
 export type CrudFieldType = 'text' | 'string' | 'textarea' | 'select' | 'radio' | 'multi-select' | 'boolean' | 'checkbox' | 'email' | 'url' | 'tel' | 'password' | 'number' | 'date' | 'datetime' | 'date-range' | 'custom';
-/** 可解析为字符串的文本值（支持 i18n 函数）。 */
+/**
+ * 可解析为字符串的文本值（支持 i18n 函数）。
+ *
+ * @example
+ * ```ts
+ * import type { CrudText } from '@h-ai/ui'
+ * const example: CrudText = () => '邮箱'
+ * ```
+ */
 export type CrudText = string | (() => string);
-/** 选项项（select / radio / multi-select）。 */
+/**
+ * 选项项（select / radio / multi-select）。
+ *
+ * @example
+ * ```ts
+ * import type { CrudOption } from '@h-ai/ui'
+ * const example: CrudOption = { label: '启用', value: true }
+ * ```
+ */
 export interface CrudOption {
     label: string;
     value: string | number | boolean;
 }
-/** 字段定义（与 `CrudPage` 的字段模型对齐）。 */
+/**
+ * 字段定义（与 `CrudPage` 的字段模型对齐）。
+ *
+ * @example
+ * ```ts
+ * import type { CrudFieldDef } from '@h-ai/ui'
+ * const example: CrudFieldDef = { id: 'email', label: '邮箱', type: 'email', inList: true, validation: { required: true } }
+ * ```
+ */
 export interface CrudFieldDef {
     /** 字段 id（对应数据对象的属性名）。 */
     id: string;
@@ -73,12 +105,29 @@ export interface CrudFieldDef {
     /** 排序权重（升序）。 */
     order?: number;
 }
-/** 列表请求附加项；用于 latest-wins 取消旧请求。 */
+/**
+ * 列表请求附加项；用于 latest-wins 取消旧请求。
+ *
+ * @example
+ * ```ts
+ * import type { CrudListOptions } from '@h-ai/ui'
+ * const example: CrudListOptions = { signal: new AbortController().signal }
+ * ```
+ */
 export interface CrudListOptions {
     /** 取消信号；旧请求被新请求取代时触发 abort。 */
     signal?: AbortSignal;
 }
-/** CRUD API 集合。列表返回标准 `PaginatedResult<T>`，避免各页面重复 page/pageSize/total 映射。 */
+/**
+ * CRUD API 集合。列表返回标准 `PaginatedResult<T>`，避免各页面重复 page/pageSize/total 映射。
+ * @typeParam T - 字段值或资源条目的数据类型。
+ *
+ * @example
+ * ```ts
+ * import type { CrudApi } from '@h-ai/ui'
+ * const example: CrudApi<Record<string, unknown>> = { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) }
+ * ```
+ */
 export interface CrudApi<T> {
     /** 分页列表；第二参数携带取消信号，实现方可透传给 fetch。 */
     list: (params: Record<string, unknown>, options?: CrudListOptions) => Promise<PaginatedResult<T>>;
@@ -91,7 +140,16 @@ export interface CrudApi<T> {
     /** 删除一条记录。 */
     remove?: (id: string) => Promise<void>;
 }
-/** 资源定义。 */
+/**
+ * 资源定义。
+ * @typeParam T - 字段值或资源条目的数据类型。
+ *
+ * @example
+ * ```ts
+ * import type { CrudResource } from '@h-ai/ui'
+ * const example: CrudResource<Record<string, unknown>> = { name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } }
+ * ```
+ */
 export interface CrudResource<T> {
     /** 资源名称（用于识别业务实体）。 */
     name: string;
@@ -110,7 +168,15 @@ export interface CrudResource<T> {
     /** 资源 CRUD API。 */
     api: CrudApi<T>;
 }
-/** DataTable 列定义（适配 `CrudPage`）。 */
+/**
+ * DataTable 列定义（适配 `CrudPage`）。
+ *
+ * @example
+ * ```ts
+ * import type { CrudTableColumn } from '@h-ai/ui'
+ * const example: CrudTableColumn = { key: 'email', label: '邮箱', width: '16rem' }
+ * ```
+ */
 export interface CrudTableColumn {
     key: string;
     label: string;
@@ -118,7 +184,18 @@ export interface CrudTableColumn {
     align?: 'left' | 'center' | 'right';
     render?: (item: Record<string, unknown>) => string;
 }
-/** `CrudPage` 所需的 crud 对象形状（`defineCrud` 的返回值）。 */
+/**
+ * `CrudPage` 所需的 crud 对象形状（`defineCrud` 的返回值）。
+ * @typeParam T - 字段值或资源条目的数据类型。
+ *
+ * @example
+ * ```ts
+ * import { defineCrud } from '@h-ai/ui'
+ * import type { CrudDef } from '@h-ai/ui'
+ * const definition: CrudDef<Record<string, unknown>> = defineCrud({ name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } })
+ * const columns = definition.toTableColumns()
+ * ```
+ */
 export interface CrudDef<T> {
     resource: CrudResource<T>;
     getListFields: () => CrudFieldDef[];
@@ -130,7 +207,16 @@ export interface CrudDef<T> {
     getDefaultValues: () => Record<string, unknown>;
     api: CrudApi<T>;
 }
-/** `CrudPage` 的 `data` 形状。 */
+/**
+ * `CrudPage` 的 `data` 形状。
+ * @typeParam T - 字段值或资源条目的数据类型。
+ *
+ * @example
+ * ```ts
+ * import type { CrudData } from '@h-ai/ui'
+ * const example: CrudData<Record<string, unknown>> = { items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20, filters: { active: true } }
+ * ```
+ */
 export interface CrudData<T> {
     items: T[];
     total: number;
@@ -138,7 +224,21 @@ export interface CrudData<T> {
     pageSize: number;
     filters: Record<string, unknown>;
 }
-/** CRUD 控制器：托管列表数据与 SPA 导航适配器。 */
+/**
+ * CRUD 控制器：托管列表数据与 SPA 导航适配器。
+ * @typeParam T - 字段值或资源条目的数据类型。
+ *
+ * @example
+ * ```ts
+ * import { defineCrud, createCrudController } from '@h-ai/ui'
+ * import type { CrudController } from '@h-ai/ui'
+ * const crud = defineCrud({ name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } })
+ * const controller: CrudController<Record<string, unknown>> = createCrudController(crud, { autoLoad: false, syncUrl: false })
+ * await controller.load()
+ * if (controller.error) throw controller.error
+ * const users = controller.data.items
+ * ```
+ */
 export interface CrudController<T> {
     /** 传给 `<CrudPage data={...}>` 的响应式数据对象。 */
     readonly data: CrudData<T>;
@@ -155,7 +255,15 @@ export interface CrudController<T> {
     /** 最新一轮请求错误；已有成功数据时仍保留原列表。 */
     readonly error: Error | undefined;
 }
-/** CRUD 控制器创建选项。 */
+/**
+ * CRUD 控制器创建选项。
+ *
+ * @example
+ * ```ts
+ * import type { CrudControllerOptions } from '@h-ai/ui'
+ * const example: CrudControllerOptions = { autoLoad: false, keepPreviousData: true, syncUrl: true }
+ * ```
+ */
 export interface CrudControllerOptions {
     /** 是否在创建后立即加载；不可见 / 惰性页签应设为 false（默认 true）。 */
     autoLoad?: boolean;
@@ -173,9 +281,15 @@ export interface CrudControllerOptions {
  * @param result - 后端返回的分页结果。
  * @param map - 单条映射函数。
  * @returns 条目被映射、分页元数据不变的新分页结果。
+ * @typeParam T - 字段值或资源条目的数据类型。
+ * @typeParam R - 转换结果的数据类型。
  *
  * @example
- * list: async (params) => mapPaginated(await api.listUsers(params), toRow)
+ * ```ts
+ * import { mapPaginated } from '@h-ai/ui'
+ * const page = mapPaginated({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }, user => ({ ...user, label: user.email }))
+ * const email = page.items[0]?.label
+ * ```
  */
 export declare function mapPaginated<T, R>(result: PaginatedResult<T>, map: (item: T, index: number) => R): PaginatedResult<R>;
 /**
@@ -185,14 +299,14 @@ export declare function mapPaginated<T, R>(result: PaginatedResult<T>, map: (ite
  *
  * @param resource - 资源定义（字段、标签、API）。
  * @returns `CrudPage` 可直接消费的 `crud` 对象。
+ * @typeParam T - 字段值或资源条目的数据类型。
  *
  * @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) },
- * })
+ * ```ts
+ * import { defineCrud } from '@h-ai/ui'
+ * const crud = defineCrud({ name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } })
+ * const columns = crud.toTableColumns()
+ * ```
  */
 export declare function defineCrud<T extends Record<string, unknown>>(resource: CrudResource<T>): CrudDef<T>;
 /**
@@ -206,11 +320,16 @@ export declare function defineCrud<T extends Record<string, unknown>>(resource:
  * @param crud - `defineCrud` 的返回值。
  * @param options - 加载策略；默认立即加载、失败保留旧数据、回填地址栏。
  * @returns 含响应式 `data`、`nav` 适配器与 `load` / `reload` 的控制器。
+ * @typeParam T - 字段值或资源条目的数据类型。
  *
  * @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} />
+ * ```ts
+ * import { defineCrud, createCrudController } from '@h-ai/ui'
+ * const crud = defineCrud({ name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } })
+ * const controller = createCrudController(crud, { autoLoad: false, syncUrl: false })
+ * await controller.load()
+ * if (controller.error) throw controller.error
+ * const users = controller.data.items
+ * ```
  */
 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

@@ -28,9 +28,15 @@ function resolveText(text) {
  * @param result - 后端返回的分页结果。
  * @param map - 单条映射函数。
  * @returns 条目被映射、分页元数据不变的新分页结果。
+ * @typeParam T - 字段值或资源条目的数据类型。
+ * @typeParam R - 转换结果的数据类型。
  *
  * @example
- * list: async (params) => mapPaginated(await api.listUsers(params), toRow)
+ * ```ts
+ * import { mapPaginated } from '@h-ai/ui'
+ * const page = mapPaginated({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }, user => ({ ...user, label: user.email }))
+ * const email = page.items[0]?.label
+ * ```
  */
 export function mapPaginated(result, map) {
     return {
@@ -47,14 +53,14 @@ export function mapPaginated(result, map) {
  *
  * @param resource - 资源定义（字段、标签、API）。
  * @returns `CrudPage` 可直接消费的 `crud` 对象。
+ * @typeParam T - 字段值或资源条目的数据类型。
  *
  * @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) },
- * })
+ * ```ts
+ * import { defineCrud } from '@h-ai/ui'
+ * const crud = defineCrud({ name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } })
+ * const columns = crud.toTableColumns()
+ * ```
  */
 export function defineCrud(resource) {
     const fields = [...resource.fields].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
@@ -91,12 +97,17 @@ export function defineCrud(resource) {
  * @param crud - `defineCrud` 的返回值。
  * @param options - 加载策略；默认立即加载、失败保留旧数据、回填地址栏。
  * @returns 含响应式 `data`、`nav` 适配器与 `load` / `reload` 的控制器。
+ * @typeParam T - 字段值或资源条目的数据类型。
  *
  * @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} />
+ * ```ts
+ * import { defineCrud, createCrudController } from '@h-ai/ui'
+ * const crud = defineCrud({ name: 'users', label: '用户', fields: [{ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }], api: { list: async () => ({ items: [{ id: 'u1', email: 'ada@example.com' }], total: 1, page: 1, pageSize: 20 }) } })
+ * const controller = createCrudController(crud, { autoLoad: false, syncUrl: false })
+ * await controller.load()
+ * if (controller.error) throw controller.error
+ * const users = controller.data.items
+ * ```
  */
 export function createCrudController(crud, options = {}) {
     const defaultPageSize = crud.resource.defaultPageSize ?? 10;

package/dist/components/scenes/crud/crud-form-validation.d.ts

@@ -1,4 +1,16 @@
 /** CRUD 客户端字段校验；仅返回消息键，避免错误文案锁定在提交时的语言。 */
 import type { FormValidationIssue } from '../../../internal/form-validation.svelte.js';
 import type { CrudFieldDef } from './crud-controller.svelte.js';
+/**
+ * 按字段类型和声明约束生成可翻译错误，不承担服务端验证。
+ * @param field - 需要校验的 CRUD 字段定义。
+ * @param value - 待处理或校验的值。
+ * @returns 可翻译的约束错误；合法输入返回 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const issue = getCrudValidationIssue({ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }, '')
+ * const key = issue?.key
+ * ```
+ */
 export declare function getCrudValidationIssue(field: CrudFieldDef, value: unknown): FormValidationIssue | undefined;

package/dist/components/scenes/crud/crud-form-validation.js

@@ -1,3 +1,15 @@
+/**
+ * 按字段类型和声明约束生成可翻译错误，不承担服务端验证。
+ * @param field - 需要校验的 CRUD 字段定义。
+ * @param value - 待处理或校验的值。
+ * @returns 可翻译的约束错误；合法输入返回 undefined。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const issue = getCrudValidationIssue({ id: 'email', label: '邮箱', type: 'email', validation: { required: true } }, '')
+ * const key = issue?.key
+ * ```
+ */
 export function getCrudValidationIssue(field, value) {
     const rules = field.validation;
     const empty = value === undefined || value === null || (typeof value === 'string' && !value.trim()) || (Array.isArray(value) && value.length === 0);