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

package/dist/components/compounds/MessageBoxContainer.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component MessageBoxContainer
   =============================================================================
   @h-ai/ui - MessageBoxContainer 组件
   =============================================================================
@@ -7,6 +8,16 @@
 
   使用 DaisyUI 样式 + tabler icon，不依赖 ElementUI。
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { MessageBoxContainer } from '@h-ai/ui'
+  const props: ComponentProps<typeof MessageBoxContainer> = { 'data-testid': 'message-boxes' }
+  const component = mount(MessageBoxContainer, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../types.js'

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

@@ -1,4 +1,25 @@
 import type { DataAttributes } from '../../types.js';
+/**
+ * MessageBoxContainer
+ * =============================================================================
+ * @h-ai/ui - MessageBoxContainer 组件
+ * =============================================================================
+ * 命令式弹框容器，渲染 messageBox store 中的所有弹框。
+ * 每个弹框由 MessageBoxDialog 独立管理 showModal()/close()。
+ *
+ * 使用 DaisyUI 样式 + tabler icon，不依赖 ElementUI。
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { MessageBoxContainer } from '@h-ai/ui'
+ * const props: ComponentProps<typeof MessageBoxContainer> = { 'data-testid': 'message-boxes' }
+ * const component = mount(MessageBoxContainer, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const MessageBoxContainer: import("svelte").Component<DataAttributes, {}, "">;
 type MessageBoxContainer = ReturnType<typeof MessageBoxContainer>;
 export default MessageBoxContainer;

package/dist/components/compounds/MessageBoxDialog.svelte

@@ -1,9 +1,23 @@
 <!--
+  @component MessageBoxDialog
   单个 MessageBox 弹框，由 MessageBoxContainer 渲染。
   内部使用原生 <dialog>.showModal() 进入浏览器 top layer。
   行为对标 ElementUI MessageBox：
     - 始终显示标题（默认"提示"）和右上角关闭按钮；
     - 遮罩层点击可通过 closeOnClickModal 配置。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import { MessageBoxDialog, messageBox } from '@h-ai/ui'
+  const response = messageBox.confirm({ title: '确认', message: '提交资料？' })
+  const item = messageBox.items[0]
+  if (!item) throw new Error('Dialog state unavailable')
+  const dialog = mount(MessageBoxDialog, { target: document.body, props: { item } })
+  messageBox.handleCancel(item)
+  const accepted = await response
+  await unmount(dialog)
+  ```
 -->
 <script lang='ts'>
   import type { MessageBoxItem } from '../../messagebox.svelte.js'

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

@@ -3,6 +3,27 @@ import type { DataAttributes } from '../../types.js';
 type $$ComponentProps = {
     item: MessageBoxItem;
 } & DataAttributes;
+/**
+ * MessageBoxDialog
+ * 单个 MessageBox 弹框，由 MessageBoxContainer 渲染。
+ * 内部使用原生 <dialog>.showModal() 进入浏览器 top layer。
+ * 行为对标 ElementUI MessageBox：
+ *   - 始终显示标题（默认"提示"）和右上角关闭按钮；
+ *   - 遮罩层点击可通过 closeOnClickModal 配置。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import { MessageBoxDialog, messageBox } from '@h-ai/ui'
+ * const response = messageBox.confirm({ title: '确认', message: '提交资料？' })
+ * const item = messageBox.items[0]
+ * if (!item) throw new Error('Dialog state unavailable')
+ * const dialog = mount(MessageBoxDialog, { target: document.body, props: { item } })
+ * messageBox.handleCancel(item)
+ * const accepted = await response
+ * await unmount(dialog)
+ * ```
+ */
 declare const MessageBoxDialog: import("svelte").Component<$$ComponentProps, {}, "">;
 type MessageBoxDialog = ReturnType<typeof MessageBoxDialog>;
 export default MessageBoxDialog;

package/dist/components/compounds/MessageContainer.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component MessageContainer
   =============================================================================
   @h-ai/ui - MessageContainer 组件
   =============================================================================
@@ -7,6 +8,16 @@
 
   叠加策略：消息层始终挂载到 `document.body`，使用 fixed overlay + 超高 z-index（高于 Modal 的 `--hai-z-modal`），保证不被任何弹层遮挡；空消息时隐藏容器避免拦截交互。
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { MessageContainer } from '@h-ai/ui'
+  const props: ComponentProps<typeof MessageContainer> = { 'data-testid': 'messages' }
+  const component = mount(MessageContainer, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../types.js'

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

@@ -1,4 +1,25 @@
 import type { DataAttributes } from '../../types.js';
+/**
+ * MessageContainer
+ * =============================================================================
+ * @h-ai/ui - MessageContainer 组件
+ * =============================================================================
+ * 轻量消息提示容器，渲染 message store 中的消息条目。
+ * 视觉风格：顶部居中、带类型图标、自动滑入滑出。
+ *
+ * 叠加策略：消息层始终挂载到 `document.body`，使用 fixed overlay + 超高 z-index（高于 Modal 的 `--hai-z-modal`），保证不被任何弹层遮挡；空消息时隐藏容器避免拦截交互。
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { MessageContainer } from '@h-ai/ui'
+ * const props: ComponentProps<typeof MessageContainer> = { 'data-testid': 'messages' }
+ * const component = mount(MessageContainer, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const MessageContainer: import("svelte").Component<DataAttributes, {}, "">;
 type MessageContainer = ReturnType<typeof MessageContainer>;
 export default MessageContainer;

package/dist/components/compounds/Modal.svelte

@@ -1,6 +1,16 @@
 <!--
   @component Modal
   模态框组件，支持 backdrop-blur 和 scale-in 动画。
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Modal } from '@h-ai/ui'
+  const props: ComponentProps<typeof Modal> = { open: true, title: '编辑资料', closeOnBackdrop: false, children: createRawSnippet(() => ({ render: () => "<span>表单内容</span>" })) }
+  const component = mount(Modal, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, ModalProps } from '../../types.js'

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

@@ -3,6 +3,16 @@ type $$ComponentProps = ModalProps & DataAttributes;
 /**
  * Modal
  * 模态框组件，支持 backdrop-blur 和 scale-in 动画。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Modal } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Modal> = { open: true, title: '编辑资料', closeOnBackdrop: false, children: createRawSnippet(() => ({ render: () => "<span>表单内容</span>" })) }
+ * const component = mount(Modal, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const Modal: import("svelte").Component<$$ComponentProps, {}, "open">;
 type Modal = ReturnType<typeof Modal>;

package/dist/components/compounds/PageHeader.svelte

@@ -7,20 +7,33 @@
   @prop {Snippet} actions - 右侧操作按钮插槽
 
   @example
-  <PageHeader title="用户管理" description="管理系统用户">
-    {#snippet actions()}
-      <Button onclick={createUser}>
-        <span class='icon-[tabler--plus] size-4'></span>
-        新建用户
-      </Button>
-    {/snippet}
-  </PageHeader>
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { PageHeader } from '@h-ai/ui'
+  const props: ComponentProps<typeof PageHeader> = { title: '用户管理', description: '维护用户资料' }
+  const component = mount(PageHeader, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'
   import type { DataAttributes } from '../../types.js'
   import { getDataAttributes } from '../../utils.js'
 
+  /**
+   * PageHeader 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { PageHeader } from '@h-ai/ui'
+   * const props: ComponentProps<typeof PageHeader> = { title: '用户管理', description: '维护用户资料' }
+   * const component = mount(PageHeader, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     title: string
     description?: string

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

@@ -1,5 +1,18 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../types.js';
+/**
+ * PageHeader 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { PageHeader } from '@h-ai/ui'
+ * const props: ComponentProps<typeof PageHeader> = { title: '用户管理', description: '维护用户资料' }
+ * const component = mount(PageHeader, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     title: string;
     description?: string;
@@ -16,14 +29,14 @@ type $$ComponentProps = Props & DataAttributes;
  * @prop {Snippet} actions - 右侧操作按钮插槽
  *
  * @example
- * <PageHeader title="用户管理" description="管理系统用户">
- *   {#snippet actions()}
- *     <Button onclick={createUser}>
- *       <span class='icon-[tabler--plus] size-4'></span>
- *       新建用户
- *     </Button>
- *   {/snippet}
- * </PageHeader>
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { PageHeader } from '@h-ai/ui'
+ * const props: ComponentProps<typeof PageHeader> = { title: '用户管理', description: '维护用户资料' }
+ * const component = mount(PageHeader, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const PageHeader: import("svelte").Component<$$ComponentProps, {}, "">;
 type PageHeader = ReturnType<typeof PageHeader>;

package/dist/components/compounds/Pagination.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Pagination
   =============================================================================
   @h-ai/ui - Pagination 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $derived, $bindable)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Pagination } from '@h-ai/ui'
+  const props: ComponentProps<typeof Pagination> = { page: 1, total: 42, pageSize: 10 }
+  const component = mount(Pagination, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, PaginationProps } from '../../types.js'
@@ -35,6 +46,7 @@
   }: PaginationProps & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
+  const controlId = $props.id()
   // labels 优先，缺省回退到内置消息 uiM(...)
 
   // 计算总页数（至少 1 页，保证分页栏在空数据时仍可渲染）
@@ -51,7 +63,8 @@
       : 'w-[2.5rem] shrink-0 [&>.fieldset]:m-0 [&>.fieldset]:min-w-0',
   )
 
-  let jumperValue = $state(String(page))
+  // 可写派生值保留编辑草稿，父级页码变化时自动恢复实际值。
+  let jumperValue = $derived(String(page))
 
   function goToPage(p: number) {
     const clamped = Math.max(1, Math.min(totalPages, Math.round(p)))
@@ -108,9 +121,10 @@
   <div class={rowGapClass}>
     {#if showSizeChanger}
       <div class='flex items-center gap-2'>
-        <span class={tableTextClass}>{labels.rowsPerPage ?? uiM('pagination_rows_per_page')}</span>
+        <label for={`${controlId}-size`} class={tableTextClass}>{labels.rowsPerPage ?? uiM('pagination_rows_per_page')}</label>
         <div class={sizeChangerClass}>
           <Select
+            id={`${controlId}-size`}
             size={controlSize}
             value={String(pageSize)}
             options={pageSizeSelectOptions}
@@ -121,23 +135,23 @@
     {/if}
 
     {#if showPageInfo}
-      <span class={tableTextClass}>{pageInfoText}</span>
+      <span class={tableTextClass} aria-live='polite' aria-atomic='true'>{pageInfoText}</span>
     {/if}
 
-    <div class='flex items-center gap-1'>
+    <div class='hai-pagination__navigation flex items-center gap-1'>
       {#if showFirstLast}
-        <BareButton class={navBtnClass} disabled={page === 1} onclick={() => goToPage(1)} ariaLabel='First page'>
+        <BareButton class={navBtnClass} disabled={page === 1} onclick={() => goToPage(1)} ariaLabel={uiM('pagination_first')}>
           <span class={cn('icon-[tabler--chevrons-left]', navIconClass)}></span>
         </BareButton>
       {/if}
-      <BareButton class={navBtnClass} disabled={page === 1} onclick={() => goToPage(page - 1)} ariaLabel='Previous page'>
+      <BareButton class={navBtnClass} disabled={page === 1} onclick={() => goToPage(page - 1)} ariaLabel={uiM('pagination_previous')}>
         <span class={cn('icon-[tabler--chevron-left]', navIconClass)}></span>
       </BareButton>
-      <BareButton class={navBtnClass} disabled={page === totalPages} onclick={() => goToPage(page + 1)} ariaLabel='Next page'>
+      <BareButton class={navBtnClass} disabled={page === totalPages} onclick={() => goToPage(page + 1)} ariaLabel={uiM('pagination_next')}>
         <span class={cn('icon-[tabler--chevron-right]', navIconClass)}></span>
       </BareButton>
       {#if showFirstLast}
-        <BareButton class={navBtnClass} disabled={page === totalPages} onclick={() => goToPage(totalPages)} ariaLabel='Last page'>
+        <BareButton class={navBtnClass} disabled={page === totalPages} onclick={() => goToPage(totalPages)} ariaLabel={uiM('pagination_last')}>
           <span class={cn('icon-[tabler--chevrons-right]', navIconClass)}></span>
         </BareButton>
       {/if}
@@ -147,7 +161,9 @@
       <div class={jumperWrapClass}>
         <span class={tableTextClass}>{labels.jumpTo ?? uiM('pagination_jump_to')}</span>
         <div class={jumperInputClass}>
+          <label for={`${controlId}-jump`} class='sr-only'>{uiM('pagination_jump_label')}</label>
           <Input
+            id={`${controlId}-jump`}
             type='number'
             size={jumperControlSize}
             class='h-7 w-full rounded-md [&_input]:px-1.5 [&_input]:text-center [&_input]:text-[12px]'
@@ -163,3 +179,13 @@
     {/if}
   </div>
 </div>
+
+<style>
+  /* 桌面保持紧凑；触摸设备扩大真实命中区域。 */
+  @media (pointer: coarse) {
+    .hai-pagination__navigation :global(button) {
+      min-width: var(--hai-touch-target-min, 44px);
+      min-height: var(--hai-touch-target-min, 44px);
+    }
+  }
+</style>

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

@@ -1,5 +1,25 @@
 import type { DataAttributes, PaginationProps } from '../../types.js';
 type $$ComponentProps = PaginationProps & DataAttributes;
+/**
+ * Pagination
+ * =============================================================================
+ * @h-ai/ui - Pagination 组件
+ * =============================================================================
+ * 分页组件
+ *
+ * 使用 Svelte 5 Runes ($props, $derived, $bindable)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Pagination } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Pagination> = { page: 1, total: 42, pageSize: 10 }
+ * const component = mount(Pagination, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Pagination: import("svelte").Component<$$ComponentProps, {}, "page">;
 type Pagination = ReturnType<typeof Pagination>;
 export default Pagination;

package/dist/components/compounds/Popover.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Popover
   =============================================================================
   @h-ai/ui - Popover 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $state, $effect)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Popover } from '@h-ai/ui'
+  const props: ComponentProps<typeof Popover> = { position: 'bottom', portal: true, children: createRawSnippet(() => ({ render: () => "<span>提示内容</span>" })) }
+  const component = mount(Popover, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, PopoverProps } from '../../types.js'

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

@@ -1,5 +1,25 @@
 import type { DataAttributes, PopoverProps } from '../../types.js';
 type $$ComponentProps = PopoverProps & DataAttributes;
+/**
+ * Popover
+ * =============================================================================
+ * @h-ai/ui - Popover 组件
+ * =============================================================================
+ * 弹出层组件
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $effect)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Popover } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Popover> = { position: 'bottom', portal: true, children: createRawSnippet(() => ({ render: () => "<span>提示内容</span>" })) }
+ * const component = mount(Popover, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Popover: import("svelte").Component<$$ComponentProps, {}, "open">;
 type Popover = ReturnType<typeof Popover>;
 export default Popover;

package/dist/components/compounds/PullRefresh.svelte

@@ -1,16 +1,40 @@
 <!--
+  @component PullRefresh
   @h-ai/ui — PullRefresh（下拉刷新）
 
   用法：
   <PullRefresh onrefresh={async () => await loadData()} >
     <div>列表内容</div>
   </PullRefresh>
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { PullRefresh } from '@h-ai/ui'
+  const props: ComponentProps<typeof PullRefresh> = { threshold: 80, children: createRawSnippet(() => ({ render: () => "<p>可下拉更新的内容。</p>" })) }
+  const component = mount(PullRefresh, { 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'
 
+  /**
+   * PullRefresh 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount, createRawSnippet } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { PullRefresh } from '@h-ai/ui'
+   * const props: ComponentProps<typeof PullRefresh> = { threshold: 80, children: createRawSnippet(() => ({ render: () => "<p>可下拉更新的内容。</p>" })) }
+   * const component = mount(PullRefresh, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 刷新回调（需返回 Promise） */
     onrefresh?: () => Promise<void>

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

@@ -1,5 +1,18 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../types.js';
+/**
+ * PullRefresh 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { PullRefresh } from '@h-ai/ui'
+ * const props: ComponentProps<typeof PullRefresh> = { threshold: 80, children: createRawSnippet(() => ({ render: () => "<p>可下拉更新的内容。</p>" })) }
+ * const component = mount(PullRefresh, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 刷新回调（需返回 Promise） */
     onrefresh?: () => Promise<void>;
@@ -13,6 +26,25 @@ interface Props {
     children: Snippet;
 }
 type $$ComponentProps = Props & DataAttributes;
+/**
+ * PullRefresh
+ * @h-ai/ui — PullRefresh（下拉刷新）
+ *
+ * 用法：
+ * <PullRefresh onrefresh={async () => await loadData()} >
+ *   <div>列表内容</div>
+ * </PullRefresh>
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { PullRefresh } from '@h-ai/ui'
+ * const props: ComponentProps<typeof PullRefresh> = { threshold: 80, children: createRawSnippet(() => ({ render: () => "<p>可下拉更新的内容。</p>" })) }
+ * const component = mount(PullRefresh, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const PullRefresh: import("svelte").Component<$$ComponentProps, {}, "">;
 type PullRefresh = ReturnType<typeof PullRefresh>;
 export default PullRefresh;

package/dist/components/compounds/Result.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Result
   =============================================================================
   @h-ai/ui - Result 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $derived)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Result } from '@h-ai/ui'
+  const props: ComponentProps<typeof Result> = { status: 'success', title: '提交完成' }
+  const component = mount(Result, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, ResultProps } from '../../types.js'

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

@@ -1,5 +1,25 @@
 import type { DataAttributes, ResultProps } from '../../types.js';
 type $$ComponentProps = ResultProps & DataAttributes;
+/**
+ * Result
+ * =============================================================================
+ * @h-ai/ui - Result 组件
+ * =============================================================================
+ * 结果页展示组件，用于操作反馈
+ *
+ * 使用 Svelte 5 Runes ($props, $derived)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Result } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Result> = { status: 'success', title: '提交完成' }
+ * const component = mount(Result, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Result: import("svelte").Component<$$ComponentProps, {}, "">;
 type Result = ReturnType<typeof Result>;
 export default Result;

package/dist/components/compounds/SafeArea.svelte

@@ -1,16 +1,40 @@
 <!--
+  @component SafeArea
   @h-ai/ui — SafeArea（安全区域包裹组件）
 
   用法：
   <SafeArea position="top">
     <AppBar />
   </SafeArea>
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { SafeArea } from '@h-ai/ui'
+  const props: ComponentProps<typeof SafeArea> = { position: 'all', children: createRawSnippet(() => ({ render: () => "<main>页面内容</main>" })) }
+  const component = mount(SafeArea, { 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'
 
+  /**
+   * SafeArea 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount, createRawSnippet } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { SafeArea } from '@h-ai/ui'
+   * const props: ComponentProps<typeof SafeArea> = { position: 'all', children: createRawSnippet(() => ({ render: () => "<main>页面内容</main>" })) }
+   * const component = mount(SafeArea, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 安全区域位置 */
     position?: 'top' | 'bottom' | 'all'