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

package/dist/components/scenes/ai/table/table-types.d.ts

@@ -4,8 +4,23 @@ import type { DataAttributes } from '../../../../types.js';
  * - `text`: 普通文本输入
  * - `number`: 数值输入（前端仍按字符串回传，避免输入中间态被强转）
  * - `tag`: 标签样式输入，用于优先级、状态等枚举文本
+ *
+ * @example
+ * ```ts
+ * import type { AiTableColumnType } from '@h-ai/ui'
+ * const example: AiTableColumnType = 'number'
+ * ```
  */
 export type AiTableColumnType = 'text' | 'number' | 'tag';
+/**
+ * AI 表格列的稳定字段名、标题和编辑类型。
+ *
+ * @example
+ * ```ts
+ * import type { AiTableColumn } from '@h-ai/ui'
+ * const example: AiTableColumn = { key: 'sales', label: '销量', type: 'number' }
+ * ```
+ */
 export interface AiTableColumn {
     /** 列唯一键，必须和每行对象中的字段名一一对应。 */
     key: string;
@@ -14,6 +29,15 @@ export interface AiTableColumn {
     /** 当前列的输入与渲染类型。 */
     type: AiTableColumnType;
 }
+/**
+ * 带稳定 row_id 的表格行；其余字段按列 key 访问。
+ *
+ * @example
+ * ```ts
+ * import type { AiTableRow } from '@h-ai/ui'
+ * const example: AiTableRow = { row_id: 'r1', sales: 42 }
+ * ```
+ */
 export interface AiTableRow {
     /** 行唯一标识；编辑、删除和流式合并都依赖它做稳定匹配。 */
     row_id: string;
@@ -26,6 +50,15 @@ export interface AiTableRow {
      */
     [key: string]: unknown;
 }
+/**
+ * AI 表格的完整列定义和行快照，交给编辑器进行受控展示与编辑。
+ *
+ * @example
+ * ```ts
+ * import type { AiTableData } from '@h-ai/ui'
+ * const example: AiTableData = { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 42 }] }
+ * ```
+ */
 export interface AiTableData {
     /** 列定义，按数组顺序渲染表头和单元格。 */
     table_columns: AiTableColumn[];
@@ -34,8 +67,23 @@ export interface AiTableData {
 }
 /**
  * 表格变更来源，用于上层做埋点或按动作类型分流保存策略。
+ *
+ * @example
+ * ```ts
+ * import type { AiTableEditorChangeAction } from '@h-ai/ui'
+ * const example: AiTableEditorChangeAction = 'cell-update'
+ * ```
  */
 export type AiTableEditorChangeAction = 'replace' | 'cell-update' | 'row-add' | 'row-delete' | 'row-reorder';
+/**
+ * 表格修改后的完整快照及动作定位信息；宿主据此保存，而不是依赖内部草稿。
+ *
+ * @example
+ * ```ts
+ * import type { AiTableEditorChangePayload } from '@h-ai/ui'
+ * const example: AiTableEditorChangePayload = { action: 'cell-update', rowId: 'r1', columnKey: 'sales', value: '43', nextData: { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 43 }] } }
+ * ```
+ */
 export interface AiTableEditorChangePayload {
     /** 本次变更动作类型。 */
     action: AiTableEditorChangeAction;
@@ -54,12 +102,30 @@ export interface AiTableEditorChangePayload {
     /** 行重排后的索引；仅 `row-reorder` 时存在。 */
     toIndex?: number;
 }
+/**
+ * 表格复制回调，包含当前数据和可交给剪贴板的纯文本。
+ *
+ * @example
+ * ```ts
+ * import type { AiTableCopyPayload } from '@h-ai/ui'
+ * const example: AiTableCopyPayload = { data: { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 42 }] }, text: '销量\n42' }
+ * ```
+ */
 export interface AiTableCopyPayload {
     /** 当前复制时的结构化表格数据。 */
     data: AiTableData;
     /** 复制到剪贴板的文本内容（TSV）。 */
     text: string;
 }
+/**
+ * 表格下载回调，包含当前数据、CSV 正文和建议文件名。
+ *
+ * @example
+ * ```ts
+ * import type { AiTableDownloadPayload } from '@h-ai/ui'
+ * const example: AiTableDownloadPayload = { data: { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 42 }] }, csv: '销量\n42', filename: 'sales.csv' }
+ * ```
+ */
 export interface AiTableDownloadPayload {
     /** 当前下载时的结构化表格数据。 */
     data: AiTableData;
@@ -68,6 +134,19 @@ export interface AiTableDownloadPayload {
     /** 推荐文件名（已带 `.csv` 后缀）。 */
     filename: string;
 }
+/**
+ * AI 表格编辑器的输入快照、展示状态和宿主保存/复制/下载回调。
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { AiTableEditor } from '@h-ai/ui'
+ *   import type { AiTableEditorProps } from '@h-ai/ui'
+ *   const props: AiTableEditorProps = { title: '销量', tableData: { table_columns: [{ key: 'sales', label: '销量', type: 'number' }], table_rows: [{ row_id: 'r1', sales: 42 }] } }
+ * </script>
+ * <AiTableEditor {...props} />
+ * ```
+ */
 export interface AiTableEditorProps extends DataAttributes {
     /** 原始表格内容字符串，通常是 JSON 文本，支持流式残缺片段。 */
     content?: string;

package/dist/components/scenes/app/FeedbackModal.svelte

@@ -6,10 +6,14 @@
   @prop {function} onsubmit - 提交反馈的回调
 
   @example
-  <FeedbackModal
-    bind:open={showFeedback}
-    onsubmit={async (data) => { await submitFeedback(data) }}
-  />
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { FeedbackModal } from '@h-ai/ui'
+  const props: ComponentProps<typeof FeedbackModal> = { open: true, labels: { title: '提交反馈' } }
+  const component = mount(FeedbackModal, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import FormField from '../../compounds/FormField.svelte'
@@ -20,15 +24,38 @@
   import Select from '../../primitives/Select.svelte'
   import Textarea from '../../primitives/Textarea.svelte'
 
+  /**
+   * 反馈表单可选的问题类别。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: FeedbackType = 'bug'
+   * ```
+   */
   type FeedbackType = 'bug' | 'feature' | 'question' | 'other'
 
+  /**
+   * 反馈表单提交值；描述和联系方式由宿主验证并保存。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: FeedbackData = { type: 'bug', description: '保存后列表没有刷新', contact: 'ada@example.com' }
+   * ```
+   */
   interface FeedbackData {
     type: FeedbackType
     description: string
     contact?: string
   }
 
-  /** i18n 文案配置 */
+  /**
+   * i18n 文案配置
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: FeedbackLabels = { title: '提交反馈', contentLabel: '问题描述' }
+   * ```
+   */
   interface FeedbackLabels {
     title?: string
     description?: string
@@ -53,6 +80,19 @@
   import { uiM } from '../../../messages.js'
   import { getDataAttributes } from '../../../utils.js'
 
+  /**
+   * FeedbackModal 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { FeedbackModal } from '@h-ai/ui'
+   * const props: ComponentProps<typeof FeedbackModal> = { open: true, labels: { title: '提交反馈' } }
+   * const component = mount(FeedbackModal, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props extends FormLayoutOptions {
     open?: boolean
     labels?: FeedbackLabels

package/dist/components/scenes/app/FeedbackModal.svelte.d.ts

@@ -1,11 +1,34 @@
 import type { DataAttributes, FormLayoutOptions } from '../../../types.js';
+/**
+ * 反馈表单可选的问题类别。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FeedbackType = 'bug'
+ * ```
+ */
 type FeedbackType = 'bug' | 'feature' | 'question' | 'other';
+/**
+ * 反馈表单提交值；描述和联系方式由宿主验证并保存。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FeedbackData = { type: 'bug', description: '保存后列表没有刷新', contact: 'ada@example.com' }
+ * ```
+ */
 interface FeedbackData {
     type: FeedbackType;
     description: string;
     contact?: string;
 }
-/** i18n 文案配置 */
+/**
+ * i18n 文案配置
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FeedbackLabels = { title: '提交反馈', contentLabel: '问题描述' }
+ * ```
+ */
 interface FeedbackLabels {
     title?: string;
     description?: string;
@@ -25,6 +48,19 @@ interface FeedbackLabels {
         other?: string;
     };
 }
+/**
+ * FeedbackModal 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { FeedbackModal } from '@h-ai/ui'
+ * const props: ComponentProps<typeof FeedbackModal> = { open: true, labels: { title: '提交反馈' } }
+ * const component = mount(FeedbackModal, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props extends FormLayoutOptions {
     open?: boolean;
     labels?: FeedbackLabels;
@@ -40,10 +76,14 @@ type $$ComponentProps = Props & DataAttributes;
  * @prop {function} onsubmit - 提交反馈的回调
  *
  * @example
- * <FeedbackModal
- *   bind:open={showFeedback}
- *   onsubmit={async (data) => { await submitFeedback(data) }}
- * />
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { FeedbackModal } from '@h-ai/ui'
+ * const props: ComponentProps<typeof FeedbackModal> = { open: true, labels: { title: '提交反馈' } }
+ * const component = mount(FeedbackModal, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const FeedbackModal: import("svelte").Component<$$ComponentProps, {}, "open">;
 type FeedbackModal = ReturnType<typeof FeedbackModal>;

package/dist/components/scenes/app/LanguageSwitch.svelte

@@ -7,25 +7,13 @@
   @prop {function} onchange - 语言变更回调，传入选中的语言代码
 
   @example
-  ```svelte
-  <script>
-    import { LanguageSwitch, createLocaleStore, setGlobalLocale } from '@h-ai/ui'
-    import { setLocale, getLocale } from '$lib/paraglide/runtime.js'
-
-    const localeStore = createLocaleStore()
-  </script>
-
-  <LanguageSwitch
-    currentLanguage={localeStore.current}
-    languages={[
-      { value: 'zh-CN', label: '简体中文' },
-      { value: 'en-US', label: 'English' }
-    ]}
-    onchange={(lang) => {
-      localeStore.set(lang)  // 同步到 @h-ai/core 全局 locale
-      setLocale(lang)        // 同步到 Paraglide
-    }}
-  />
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { LanguageSwitch } from '@h-ai/ui'
+  const props: ComponentProps<typeof LanguageSwitch> = { currentLanguage: 'zh-CN', languages: [{ value: 'zh-CN', label: '中文' }, { value: 'en-US', label: 'English' }] }
+  const component = mount(LanguageSwitch, { target: document.body, props })
+  await unmount(component)
   ```
 -->
 <script lang='ts'>
@@ -34,12 +22,33 @@
   import { getDataAttributes } from '../../../utils.js'
   import BareButton from '../../primitives/BareButton.svelte'
 
+  /**
+   * 语言选择器候选项；value 使用应用实际支持的 locale 代码。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: Language = { value: 'zh-CN', label: '中文' }
+   * ```
+   */
   interface Language {
     value: string
     label: string
     flag?: string
   }
 
+  /**
+   * LanguageSwitch 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { LanguageSwitch } from '@h-ai/ui'
+   * const props: ComponentProps<typeof LanguageSwitch> = { currentLanguage: 'zh-CN', languages: [{ value: 'zh-CN', label: '中文' }, { value: 'en-US', label: 'English' }] }
+   * const component = mount(LanguageSwitch, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 当前语言代码（BCP 47 格式） */
     currentLanguage?: string
@@ -60,6 +69,7 @@
     languages = [
       { value: 'zh-CN', label: '简体中文', flag: 'CN' },
       { value: 'en-US', label: 'English', flag: 'US' },
+      { value: 'ja-JP', label: '日本語', flag: 'JP' },
     ],
     onchange,
     align = 'end',

package/dist/components/scenes/app/LanguageSwitch.svelte.d.ts

@@ -1,9 +1,30 @@
 import type { DataAttributes } from '../../../types.js';
+/**
+ * 语言选择器候选项；value 使用应用实际支持的 locale 代码。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: Language = { value: 'zh-CN', label: '中文' }
+ * ```
+ */
 interface Language {
     value: string;
     label: string;
     flag?: string;
 }
+/**
+ * LanguageSwitch 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { LanguageSwitch } from '@h-ai/ui'
+ * const props: ComponentProps<typeof LanguageSwitch> = { currentLanguage: 'zh-CN', languages: [{ value: 'zh-CN', label: '中文' }, { value: 'en-US', label: 'English' }] }
+ * const component = mount(LanguageSwitch, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 当前语言代码（BCP 47 格式） */
     currentLanguage?: string;
@@ -28,25 +49,13 @@ type $$ComponentProps = Props & DataAttributes;
  * @prop {function} onchange - 语言变更回调，传入选中的语言代码
  *
  * @example
- * ```svelte
- * <script>
- *   import { LanguageSwitch, createLocaleStore, setGlobalLocale } from '@h-ai/ui'
- *   import { setLocale, getLocale } from '$lib/paraglide/runtime.js'
- *
- *   const localeStore = createLocaleStore()
- * </script>
- *
- * <LanguageSwitch
- *   currentLanguage={localeStore.current}
- *   languages={[
- *     { value: 'zh-CN', label: '简体中文' },
- *     { value: 'en-US', label: 'English' }
- *   ]}
- *   onchange={(lang) => {
- *     localeStore.set(lang)  // 同步到 @h-ai/core 全局 locale
- *     setLocale(lang)        // 同步到 Paraglide
- *   }}
- * />
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { LanguageSwitch } from '@h-ai/ui'
+ * const props: ComponentProps<typeof LanguageSwitch> = { currentLanguage: 'zh-CN', languages: [{ value: 'zh-CN', label: '中文' }, { value: 'en-US', label: 'English' }] }
+ * const component = mount(LanguageSwitch, { target: document.body, props })
+ * await unmount(component)
  * ```
  */
 declare const LanguageSwitch: import("svelte").Component<$$ComponentProps, {}, "">;

package/dist/components/scenes/app/SettingsLayout.svelte

@@ -8,15 +8,14 @@
   使用 Svelte 5 Runes ($props, $derived)
 
   @example
-  <SettingsLayout
-    title="设置"
-    description="管理你的账户与偏好"
-    sections={[{ id: 'appearance', label: '外观', icon: 'icon-[tabler--palette]' }]}
-    active={active}
-    onselect={(id) => active = id}
-  >
-    {#if active === 'appearance'}<AppearanceSection />{/if}
-  </SettingsLayout>
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { SettingsLayout } from '@h-ai/ui'
+  const props: ComponentProps<typeof SettingsLayout> = { title: '设置', sections: [{ id: 'profile', label: '资料', href: '/settings/profile' }], active: 'profile', children: createRawSnippet(() => ({ render: () => "<p>个人资料设置</p>" })) }
+  const component = mount(SettingsLayout, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'
@@ -24,6 +23,19 @@
   import { cn, getDataAttributes } from '../../../utils.js'
   import BareButton from '../../primitives/BareButton.svelte'
 
+  /**
+   * 设置页分区导航项；href 直接渲染链接，否则由宿主处理选中事件。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount, createRawSnippet } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { SettingsLayout } from '@h-ai/ui'
+   * const props: ComponentProps<typeof SettingsLayout> = { title: '设置', sections: [{ id: 'profile', label: '资料', href: '/settings/profile' }], active: 'profile', children: createRawSnippet(() => ({ render: () => "<p>个人资料设置</p>" })) }
+   * const component = mount(SettingsLayout, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   type SettingsSection = {
     id: string
     label: string

package/dist/components/scenes/app/SettingsLayout.svelte.d.ts

@@ -1,5 +1,18 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../../types.js';
+/**
+ * 设置页分区导航项；href 直接渲染链接，否则由宿主处理选中事件。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { SettingsLayout } from '@h-ai/ui'
+ * const props: ComponentProps<typeof SettingsLayout> = { title: '设置', sections: [{ id: 'profile', label: '资料', href: '/settings/profile' }], active: 'profile', children: createRawSnippet(() => ({ render: () => "<p>个人资料设置</p>" })) }
+ * const component = mount(SettingsLayout, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 type SettingsSection = {
     id: string;
     label: string;
@@ -27,15 +40,14 @@ type $$ComponentProps = {
  * 使用 Svelte 5 Runes ($props, $derived)
  *
  * @example
- * <SettingsLayout
- *   title="设置"
- *   description="管理你的账户与偏好"
- *   sections={[{ id: 'appearance', label: '外观', icon: 'icon-[tabler--palette]' }]}
- *   active={active}
- *   onselect={(id) => active = id}
- * >
- *   {#if active === 'appearance'}<AppearanceSection />{/if}
- * </SettingsLayout>
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { SettingsLayout } from '@h-ai/ui'
+ * const props: ComponentProps<typeof SettingsLayout> = { title: '设置', sections: [{ id: 'profile', label: '资料', href: '/settings/profile' }], active: 'profile', children: createRawSnippet(() => ({ render: () => "<p>个人资料设置</p>" })) }
+ * const component = mount(SettingsLayout, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const SettingsLayout: import("svelte").Component<$$ComponentProps, {}, "">;
 type SettingsLayout = ReturnType<typeof SettingsLayout>;

package/dist/components/scenes/app/SettingsModal.svelte

@@ -8,6 +8,16 @@
   @prop {string} currentTheme - 当前主题
   @prop {function} onlanguagechange - 语言变更回调
   @prop {function} onthemechange - 主题变更回调
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { SettingsModal } from '@h-ai/ui'
+  const props: ComponentProps<typeof SettingsModal> = { open: true, currentLanguage: 'zh-CN', currentTheme: 'light' }
+  const component = mount(SettingsModal, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
@@ -16,6 +26,19 @@
   import BareButton from '../../primitives/BareButton.svelte'
   import IconButton from '../../primitives/IconButton.svelte'
 
+  /**
+   * SettingsModal 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { SettingsModal } from '@h-ai/ui'
+   * const props: ComponentProps<typeof SettingsModal> = { open: true, currentLanguage: 'zh-CN', currentTheme: 'light' }
+   * const component = mount(SettingsModal, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     open?: boolean
     currentLanguage?: string

package/dist/components/scenes/app/SettingsModal.svelte.d.ts

@@ -1,4 +1,17 @@
 import type { DataAttributes } from '../../../types.js';
+/**
+ * SettingsModal 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { SettingsModal } from '@h-ai/ui'
+ * const props: ComponentProps<typeof SettingsModal> = { open: true, currentLanguage: 'zh-CN', currentTheme: 'light' }
+ * const component = mount(SettingsModal, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     open?: boolean;
     currentLanguage?: string;
@@ -28,6 +41,16 @@ type $$ComponentProps = Props & DataAttributes;
  * @prop {string} currentTheme - 当前主题
  * @prop {function} onlanguagechange - 语言变更回调
  * @prop {function} onthemechange - 主题变更回调
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { SettingsModal } from '@h-ai/ui'
+ * const props: ComponentProps<typeof SettingsModal> = { open: true, currentLanguage: 'zh-CN', currentTheme: 'light' }
+ * const component = mount(SettingsModal, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const SettingsModal: import("svelte").Component<$$ComponentProps, {}, "open">;
 type SettingsModal = ReturnType<typeof SettingsModal>;

package/dist/components/scenes/app/ThemeColorPicker.svelte

@@ -5,6 +5,16 @@
   @prop {string} value - 当前选中的颜色值（Hex）
   @prop {Array<{ value: string, label: string }>} presets - 预置主题色列表
   @prop {function} onchange - 颜色变更回调
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { ThemeColorPicker } from '@h-ai/ui'
+  const props: ComponentProps<typeof ThemeColorPicker> = { value: '#2563eb', presets: [{ value: '#2563eb', label: '蓝色' }] }
+  const component = mount(ThemeColorPicker, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
@@ -15,11 +25,32 @@
   const HEX_COLOR_REGEX = /^#[0-9a-f]{6}$/
   const SHORT_HEX_COLOR_REGEX = /^#[0-9a-f]{3}$/
 
+  /**
+   * 主题色选择器的显示名称与 Hex 值。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: ThemeColorPreset = { value: '#2563eb', label: '蓝色' }
+   * ```
+   */
   interface ThemeColorPreset {
     value: string
     label: string
   }
 
+  /**
+   * ThemeColorPicker 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { ThemeColorPicker } from '@h-ai/ui'
+   * const props: ComponentProps<typeof ThemeColorPicker> = { value: '#2563eb', presets: [{ value: '#2563eb', label: '蓝色' }] }
+   * const component = mount(ThemeColorPicker, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     value?: string
     presets?: ThemeColorPreset[]

package/dist/components/scenes/app/ThemeColorPicker.svelte.d.ts

@@ -1,8 +1,29 @@
 import type { DataAttributes } from '../../../types.js';
+/**
+ * 主题色选择器的显示名称与 Hex 值。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: ThemeColorPreset = { value: '#2563eb', label: '蓝色' }
+ * ```
+ */
 interface ThemeColorPreset {
     value: string;
     label: string;
 }
+/**
+ * ThemeColorPicker 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { ThemeColorPicker } from '@h-ai/ui'
+ * const props: ComponentProps<typeof ThemeColorPicker> = { value: '#2563eb', presets: [{ value: '#2563eb', label: '蓝色' }] }
+ * const component = mount(ThemeColorPicker, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     value?: string;
     presets?: ThemeColorPreset[];
@@ -20,6 +41,16 @@ type $$ComponentProps = Props & DataAttributes;
  * @prop {string} value - 当前选中的颜色值（Hex）
  * @prop {Array<{ value: string, label: string }>} presets - 预置主题色列表
  * @prop {function} onchange - 颜色变更回调
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { ThemeColorPicker } from '@h-ai/ui'
+ * const props: ComponentProps<typeof ThemeColorPicker> = { value: '#2563eb', presets: [{ value: '#2563eb', label: '蓝色' }] }
+ * const component = mount(ThemeColorPicker, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const ThemeColorPicker: import("svelte").Component<$$ComponentProps, {}, "">;
 type ThemeColorPicker = ReturnType<typeof ThemeColorPicker>;