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

package/dist/components/compounds/DataTable.svelte

@@ -16,19 +16,15 @@
   @prop {'normal' | 'compact'} density - 显示密度，compact 为紧凑布局
 
   @example
-  <DataTable
-    data={users}
-    columns={[
-      { key: 'name', label: '姓名' },
-      { key: 'email', label: '邮箱' },
-      { key: 'createdAt', label: '创建时间', render: (item) => formatDate(item.createdAt) }
-    ]}
-    keyField="id"
-  >
-    {#snippet actions(item)}
-      <Button size="xs" onclick={() => edit(item)}>编辑</Button>
-    {/snippet}
-  </DataTable>
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { DataTable } from '@h-ai/ui'
+  const Table = DataTable<{ id: string, name: string }>
+  const props: ComponentProps<typeof Table> = { data: [{ id: 'u1', name: 'Ada' }], keyField: 'id', columns: [{ key: 'name', label: '姓名', sortable: true }] }
+  const component = mount(Table, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts' generics='T'>
   import type { Snippet } from 'svelte'
@@ -78,7 +74,20 @@
 
   /** 透传到根节点的 data-* 属性。 */
   const dataAttributes = $derived(getDataAttributes(restProps))
-  /** DataTable 内部使用的列定义。 */
+  /**
+   * DataTable 内部使用的列定义。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { DataTable } from '@h-ai/ui'
+   * const Table = DataTable<{ id: string, name: string }>
+   * const props: ComponentProps<typeof Table> = { data: [{ id: 'u1', name: 'Ada' }], keyField: 'id', columns: [{ key: 'name', label: '姓名', sortable: true }] }
+   * const component = mount(Table, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   type Column = {
     /** 列对应的数据字段。 */
     key: keyof T | string
@@ -287,12 +296,14 @@
 </script>
 
 <div {...dataAttributes} bind:this={scrollContainer} class='overflow-x-auto {className}' onscroll={syncActionColumnShadow}>
-  <table bind:this={tableElement} class={tableClass}>
+  <table bind:this={tableElement} class={tableClass} aria-busy={loading}>
     <thead>
       <tr class={headerRowClass}>
         {#each columns as col (String(col.key))}
           {@const isSorted = activeSortKey === String(col.key)}
           <th
+            scope='col'
+            aria-sort={col.sortable ? (isSorted ? (activeSortDir === 'asc' ? 'ascending' : 'descending') : 'none') : undefined}
             style={getColumnStyle(col)}
             class='{getAlignClass(col.align)} {headerCellDividerClass} relative font-medium'
           >
@@ -326,7 +337,10 @@
       {#if loading}
         <tr>
           <td colspan={columns.length + (actions ? 1 : 0)} class={placeholderCellClass}>
-            <span class='loading loading-spinner loading-sm'></span>
+            <span role='status' class='inline-flex items-center gap-2'>
+              <span class='loading loading-spinner loading-sm' aria-hidden='true'></span>
+              <span>{uiM('common_loading')}</span>
+            </span>
           </td>
         </tr>
       {:else if data.length === 0}
@@ -341,7 +355,16 @@
         </tr>
       {:else}
         {#each sortedData as item (item[keyField])}
-          <tr class='{rowClass} {onrowclick ? 'cursor-pointer' : ''}' onclick={() => onrowclick?.(item)}>
+          <tr class='{rowClass} {onrowclick ? 'cursor-pointer focus-visible:outline-2 focus-visible:outline-primary focus-visible:-outline-offset-2' : ''}'
+              tabindex={onrowclick ? 0 : undefined}
+              onclick={() => onrowclick?.(item)}
+              onkeydown={(event) => {
+                if (onrowclick && event.target === event.currentTarget && (event.key === 'Enter' || event.key === ' ')) {
+                  event.preventDefault()
+                  onrowclick(item)
+                }
+              }}
+          >
             {#each columns as col (String(col.key))}
               <td style={getColumnStyle(col)} class={getAlignClass(col.align)}>
                 {#if col.onclick}

package/dist/components/compounds/DataTable.svelte.d.ts

@@ -68,19 +68,15 @@ interface $$IsomorphicComponent {
  * @prop {'normal' | 'compact'} density - 显示密度，compact 为紧凑布局
  *
  * @example
- * <DataTable
- *   data={users}
- *   columns={[
- *     { key: 'name', label: '姓名' },
- *     { key: 'email', label: '邮箱' },
- *     { key: 'createdAt', label: '创建时间', render: (item) => formatDate(item.createdAt) }
- *   ]}
- *   keyField="id"
- * >
- *   {#snippet actions(item)}
- *     <Button size="xs" onclick={() => edit(item)}>编辑</Button>
- *   {/snippet}
- * </DataTable>
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { DataTable } from '@h-ai/ui'
+ * const Table = DataTable<{ id: string, name: string }>
+ * const props: ComponentProps<typeof Table> = { data: [{ id: 'u1', name: 'Ada' }], keyField: 'id', columns: [{ key: 'name', label: '姓名', sortable: true }] }
+ * const component = mount(Table, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const DataTable: $$IsomorphicComponent;
 type DataTable<T> = InstanceType<typeof DataTable<T>>;

package/dist/components/compounds/DatePicker.svelte

@@ -13,12 +13,13 @@
   @prop {function} onchange - 日期变更回调
 
   @example
-  ```svelte
-  <script>
-    import { CalendarDate } from '@internationalized/date'
-    let date = $state(new CalendarDate(2024, 6, 15))
-  </script>
-  <DatePicker bind:value={date} />
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { DatePicker } from '@h-ai/ui'
+  const props: ComponentProps<typeof DatePicker> = { weekStartsOn: 1, size: 'md' }
+  const component = mount(DatePicker, { target: document.body, props })
+  await unmount(component)
   ```
 -->
 <script lang='ts'>
@@ -30,6 +31,19 @@
   import { cn, getDataAttributes } from '../../utils.js'
   import { getFormControlSizeClasses } from '../control-size.js'
 
+  /**
+   * DatePicker 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { DatePicker } from '@h-ai/ui'
+   * const props: ComponentProps<typeof DatePicker> = { weekStartsOn: 1, size: 'md' }
+   * const component = mount(DatePicker, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 选中日期（双向绑定） */
     value?: DateValue

package/dist/components/compounds/DatePicker.svelte.d.ts

@@ -1,5 +1,18 @@
 import type { DateValue } from '@internationalized/date';
 import type { DataAttributes, FormText, Size } from '../../types.js';
+/**
+ * DatePicker 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { DatePicker } from '@h-ai/ui'
+ * const props: ComponentProps<typeof DatePicker> = { weekStartsOn: 1, size: 'md' }
+ * const component = mount(DatePicker, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 选中日期（双向绑定） */
     value?: DateValue;
@@ -38,12 +51,13 @@ type $$ComponentProps = Props & DataAttributes;
  * @prop {function} onchange - 日期变更回调
  *
  * @example
- * ```svelte
- * <script>
- *   import { CalendarDate } from '@internationalized/date'
- *   let date = $state(new CalendarDate(2024, 6, 15))
- * </script>
- * <DatePicker bind:value={date} />
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { DatePicker } from '@h-ai/ui'
+ * const props: ComponentProps<typeof DatePicker> = { weekStartsOn: 1, size: 'md' }
+ * const component = mount(DatePicker, { target: document.body, props })
+ * await unmount(component)
  * ```
  */
 declare const DatePicker: import("svelte").Component<$$ComponentProps, {}, "value">;

package/dist/components/compounds/Drawer.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Drawer
   =============================================================================
   @h-ai/ui - Drawer 组件
   =============================================================================
@@ -7,6 +8,16 @@
   使用 Svelte 5 Runes ($props, $derived, $effect, $bindable)
   使用 primitives 组件：IconButton
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Drawer } from '@h-ai/ui'
+  const props: ComponentProps<typeof Drawer> = { open: true, title: '详情', position: 'right', width: '28rem', children: createRawSnippet(() => ({ render: () => "<span>详情内容</span>" })) }
+  const component = mount(Drawer, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, DrawerProps } from '../../types.js'

package/dist/components/compounds/Drawer.svelte.d.ts

@@ -1,5 +1,26 @@
 import type { DataAttributes, DrawerProps } from '../../types.js';
 type $$ComponentProps = DrawerProps & DataAttributes;
+/**
+ * Drawer
+ * =============================================================================
+ * @h-ai/ui - Drawer 组件
+ * =============================================================================
+ * 抽屉组件
+ *
+ * 使用 Svelte 5 Runes ($props, $derived, $effect, $bindable)
+ * 使用 primitives 组件：IconButton
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Drawer } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Drawer> = { open: true, title: '详情', position: 'right', width: '28rem', children: createRawSnippet(() => ({ render: () => "<span>详情内容</span>" })) }
+ * const component = mount(Drawer, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Drawer: import("svelte").Component<$$ComponentProps, {}, "open">;
 type Drawer = ReturnType<typeof Drawer>;
 export default Drawer;

package/dist/components/compounds/Dropdown.svelte

@@ -1,6 +1,16 @@
 <!--
   @component Dropdown
   下拉菜单组件，支持 click/hover 触发。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Dropdown } from '@h-ai/ui'
+  const props: ComponentProps<typeof Dropdown> = { items: [{ key: 'edit', label: '编辑' }], position: 'bottom' }
+  const component = mount(Dropdown, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, DropdownProps } from '../../types.js'

package/dist/components/compounds/Dropdown.svelte.d.ts

@@ -3,6 +3,16 @@ type $$ComponentProps = DropdownProps & DataAttributes;
 /**
  * Dropdown
  * 下拉菜单组件，支持 click/hover 触发。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Dropdown } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Dropdown> = { items: [{ key: 'edit', label: '编辑' }], position: 'bottom' }
+ * const component = mount(Dropdown, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const Dropdown: import("svelte").Component<$$ComponentProps, {}, "">;
 type Dropdown = ReturnType<typeof Dropdown>;

package/dist/components/compounds/Empty.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Empty
   =============================================================================
   @h-ai/ui - Empty 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $derived)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Empty } from '@h-ai/ui'
+  const props: ComponentProps<typeof Empty> = { title: '暂无记录', icon: 'inbox' }
+  const component = mount(Empty, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, EmptyProps } from '../../types.js'
@@ -28,7 +39,7 @@
 
   const containerClass = $derived(
     cn(
-      'flex flex-col items-center justify-center py-8 text-center',
+      'flex min-w-0 flex-col items-center justify-center px-4 py-8 text-center',
       size === 'sm' && 'py-4',
       size === 'lg' && 'py-12',
       className,
@@ -46,7 +57,7 @@
 
 <div {...dataAttributes} class={containerClass}>
   <!-- 图标区域 -->
-  <div class='text-base-content/30 mb-4 {iconSize}'>
+  <div class='text-base-content/40 mb-4 shrink-0 {iconSize}' aria-hidden='true'>
     {#if children}
       {@render children()}
     {:else if icon === 'inbox'}
@@ -69,16 +80,16 @@
   </div>
 
   <!-- 标题 -->
-  <h3 class='font-medium text-base-content/70 {titleSize}'>{displayTitle}</h3>
+  <h3 class='max-w-full font-medium text-base-content/80 [overflow-wrap:anywhere] {titleSize}'>{displayTitle}</h3>
 
   <!-- 描述 -->
   {#if description}
-    <p class='mt-1 text-sm text-base-content/50 max-w-sm'>{description}</p>
+    <p class='mt-2 max-w-prose text-sm text-base-content/70 leading-relaxed [overflow-wrap:anywhere]'>{description}</p>
   {/if}
 
   <!-- 操作按钮插槽 -->
   {#if action}
-    <div class='mt-4'>
+    <div class='mt-5 flex max-w-full flex-wrap justify-center gap-2'>
       {@render action()}
     </div>
   {/if}

package/dist/components/compounds/Empty.svelte.d.ts

@@ -1,5 +1,25 @@
 import type { DataAttributes, EmptyProps } from '../../types.js';
 type $$ComponentProps = EmptyProps & DataAttributes;
+/**
+ * Empty
+ * =============================================================================
+ * @h-ai/ui - Empty 组件
+ * =============================================================================
+ * 空状态展示组件
+ *
+ * 使用 Svelte 5 Runes ($props, $derived)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Empty } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Empty> = { title: '暂无记录', icon: 'inbox' }
+ * const component = mount(Empty, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Empty: import("svelte").Component<$$ComponentProps, {}, "">;
 type Empty = ReturnType<typeof Empty>;
 export default Empty;

package/dist/components/compounds/Form.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Form
   =============================================================================
   @h-ai/ui - Form 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $state)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Form } from '@h-ai/ui'
+  const props: ComponentProps<typeof Form> = { id: 'profile-form', columns: 2, children: createRawSnippet(() => ({ render: () => "<input name=\"email\" type=\"email\" value=\"ada@example.com\" />" })) }
+  const component = mount(Form, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, FormProps } from '../../types.js'
@@ -73,12 +84,36 @@
     onreset?.()
   }
 
-  /** 重置表单 */
+  /**
+   * 重置表单
+   * @returns 无返回值；调用原生 form.reset()。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import { Form } from '@h-ai/ui'
+   * const form = mount(Form, { target: document.body, props: { id: 'profile' } })
+   * form.reset()
+   * await unmount(form)
+   * ```
+   */
   export function reset() {
     formElement?.reset()
   }
 
-  /** 获取表单数据 */
+  /**
+   * 获取表单数据
+   * @returns 当前 form 的字段值记录。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import { Form } from '@h-ai/ui'
+   * const form = mount(Form, { target: document.body, props: { id: 'profile' } })
+   * const data = form.getData()
+   * await unmount(form)
+   * ```
+   */
   export function getData(): Record<string, unknown> {
     const formData = new FormData(formElement)
     const data: Record<string, unknown> = {}

package/dist/components/compounds/Form.svelte.d.ts

@@ -1,5 +1,25 @@
 import type { DataAttributes, FormProps } from '../../types.js';
 type $$ComponentProps = FormProps & DataAttributes;
+/**
+ * Form
+ * =============================================================================
+ * @h-ai/ui - Form 组件
+ * =============================================================================
+ * 表单容器组件，提供统一的表单提交、验证和重置功能
+ *
+ * 使用 Svelte 5 Runes ($props, $state)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Form } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Form> = { id: 'profile-form', columns: 2, children: createRawSnippet(() => ({ render: () => "<input name=\"email\" type=\"email\" value=\"ada@example.com\" />" })) }
+ * const component = mount(Form, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Form: import("svelte").Component<$$ComponentProps, {
     reset: () => void;
     getData: () => Record<string, unknown>;

package/dist/components/compounds/FormField.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component FormField
   =============================================================================
   @h-ai/ui - FormField 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $derived)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { FormField } from '@h-ai/ui'
+  const props: ComponentProps<typeof FormField> = { label: '邮箱', name: 'email', required: true, children: createRawSnippet(() => ({ render: () => "<input name=\"email\" type=\"email\" />" })) }
+  const component = mount(FormField, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, FormFieldProps } from '../../types.js'

package/dist/components/compounds/FormField.svelte.d.ts

@@ -1,5 +1,25 @@
 import type { DataAttributes, FormFieldProps } from '../../types.js';
 type $$ComponentProps = FormFieldProps & DataAttributes;
+/**
+ * FormField
+ * =============================================================================
+ * @h-ai/ui - FormField 组件
+ * =============================================================================
+ * 表单字段包装器，统一 label/error/hint 展示
+ *
+ * 使用 Svelte 5 Runes ($props, $derived)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { FormField } from '@h-ai/ui'
+ * const props: ComponentProps<typeof FormField> = { label: '邮箱', name: 'email', required: true, children: createRawSnippet(() => ({ render: () => "<input name=\"email\" type=\"email\" />" })) }
+ * const component = mount(FormField, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const FormField: import("svelte").Component<$$ComponentProps, {}, "">;
 type FormField = ReturnType<typeof FormField>;
 export default FormField;

package/dist/components/compounds/FormLayout.svelte

@@ -1,4 +1,16 @@
-<!-- 表单字段布局，供 Form 和原生表单/场景组件共同复用。 -->
+<!--
+  @component FormLayout 表单字段布局，供 Form 和原生表单/场景组件共同复用。
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { FormLayout } from '@h-ai/ui'
+  const props: ComponentProps<typeof FormLayout> = { columns: 2, labelPosition: 'top', children: createRawSnippet(() => ({ render: () => "<span>表单字段</span>" })) }
+  const component = mount(FormLayout, { target: document.body, props })
+  await unmount(component)
+  ```
+-->
 <script lang='ts'>
   import type { FormLayoutProps } from '../../types.js'
   import { setContext } from 'svelte'

package/dist/components/compounds/FormLayout.svelte.d.ts

@@ -1,4 +1,17 @@
 import type { FormLayoutProps } from '../../types.js';
+/**
+ * FormLayout 表单字段布局，供 Form 和原生表单/场景组件共同复用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { FormLayout } from '@h-ai/ui'
+ * const props: ComponentProps<typeof FormLayout> = { columns: 2, labelPosition: 'top', children: createRawSnippet(() => ({ render: () => "<span>表单字段</span>" })) }
+ * const component = mount(FormLayout, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const FormLayout: import("svelte").Component<FormLayoutProps, {}, "">;
 type FormLayout = ReturnType<typeof FormLayout>;
 export default FormLayout;

package/dist/components/compounds/InfiniteScroll.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component InfiniteScroll
   @h-ai/ui — InfiniteScroll（无限滚动 / 上拉加载更多）
 
   用法：
@@ -7,12 +8,35 @@
       <div>{item.name}</div>
     {/each}
   </InfiniteScroll>
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { InfiniteScroll } from '@h-ai/ui'
+  const props: ComponentProps<typeof InfiniteScroll> = { hasMore: false, children: createRawSnippet(() => ({ render: () => "<p>已经加载全部记录。</p>" })) }
+  const component = mount(InfiniteScroll, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'
   import type { DataAttributes } from '../../types.js'
   import { cn, getDataAttributes } from '../../utils.js'
 
+  /**
+   * InfiniteScroll 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount, createRawSnippet } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { InfiniteScroll } from '@h-ai/ui'
+   * const props: ComponentProps<typeof InfiniteScroll> = { hasMore: false, children: createRawSnippet(() => ({ render: () => "<p>已经加载全部记录。</p>" })) }
+   * const component = mount(InfiniteScroll, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 加载更多回调 */
     onloadmore?: () => Promise<void>

package/dist/components/compounds/InfiniteScroll.svelte.d.ts

@@ -1,5 +1,18 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../types.js';
+/**
+ * InfiniteScroll 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { InfiniteScroll } from '@h-ai/ui'
+ * const props: ComponentProps<typeof InfiniteScroll> = { hasMore: false, children: createRawSnippet(() => ({ render: () => "<p>已经加载全部记录。</p>" })) }
+ * const component = mount(InfiniteScroll, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 加载更多回调 */
     onloadmore?: () => Promise<void>;
@@ -19,6 +32,27 @@ interface Props {
     children: Snippet;
 }
 type $$ComponentProps = Props & DataAttributes;
+/**
+ * InfiniteScroll
+ * @h-ai/ui — InfiniteScroll（无限滚动 / 上拉加载更多）
+ *
+ * 用法：
+ * <InfiniteScroll onloadmore={async () => await loadNextPage()} hasMore={hasMoreData}>
+ *   {#each items as item}
+ *     <div>{item.name}</div>
+ *   {/each}
+ * </InfiniteScroll>
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { InfiniteScroll } from '@h-ai/ui'
+ * const props: ComponentProps<typeof InfiniteScroll> = { hasMore: false, children: createRawSnippet(() => ({ render: () => "<p>已经加载全部记录。</p>" })) }
+ * const component = mount(InfiniteScroll, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const InfiniteScroll: import("svelte").Component<$$ComponentProps, {}, "">;
 type InfiniteScroll = ReturnType<typeof InfiniteScroll>;
 export default InfiniteScroll;