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

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

@@ -3,6 +3,16 @@ type $$ComponentProps = AlertProps & DataAttributes;
 /**
  * Alert
  * 警告框组件，使用 tabler icon 替代 emoji，更精致。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Alert } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Alert> = { title: '保存成功', variant: 'success', children: createRawSnippet(() => ({ render: () => "<span>操作已经完成。</span>" })) }
+ * const component = mount(Alert, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const Alert: import("svelte").Component<$$ComponentProps, {}, "">;
 type Alert = ReturnType<typeof Alert>;

package/dist/components/compounds/AppBar.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component AppBar
   @h-ai/ui — AppBar（顶部应用栏，支持安全区域）
 
   用法：
@@ -6,12 +7,35 @@
     {#snippet leading()}<BackButton />{/snippet}
     {#snippet trailing()}<Avatar />{/snippet}
   </AppBar>
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { AppBar } from '@h-ai/ui'
+  const props: ComponentProps<typeof AppBar> = { title: '设置', safeArea: true }
+  const component = mount(AppBar, { 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'
 
+  /**
+   * AppBar 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { AppBar } from '@h-ai/ui'
+   * const props: ComponentProps<typeof AppBar> = { title: '设置', safeArea: true }
+   * const component = mount(AppBar, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 标题文本 */
     title?: string

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

@@ -1,5 +1,18 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../types.js';
+/**
+ * AppBar 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { AppBar } from '@h-ai/ui'
+ * const props: ComponentProps<typeof AppBar> = { title: '设置', safeArea: true }
+ * const component = mount(AppBar, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 标题文本 */
     title?: string;
@@ -17,6 +30,26 @@ interface Props {
     children?: Snippet;
 }
 type $$ComponentProps = Props & DataAttributes;
+/**
+ * AppBar
+ * @h-ai/ui — AppBar（顶部应用栏，支持安全区域）
+ *
+ * 用法：
+ * <AppBar title="首页">
+ *   {#snippet leading()}<BackButton />{/snippet}
+ *   {#snippet trailing()}<Avatar />{/snippet}
+ * </AppBar>
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { AppBar } from '@h-ai/ui'
+ * const props: ComponentProps<typeof AppBar> = { title: '设置', safeArea: true }
+ * const component = mount(AppBar, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const AppBar: import("svelte").Component<$$ComponentProps, {}, "">;
 type AppBar = ReturnType<typeof AppBar>;
 export default AppBar;

package/dist/components/compounds/BottomNav.svelte

@@ -1,8 +1,19 @@
 <!--
+  @component BottomNav
   @h-ai/ui — BottomNav（底部导航栏）
 
   用法：
   <BottomNav items={navItems} active="home" onchange={(id) => goto(`/${id}`)} />
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { BottomNav } from '@h-ai/ui'
+  const props: ComponentProps<typeof BottomNav> = { items: [{ id: 'home', label: '首页', iconClass: 'icon-[tabler--home]' }], active: 'home', maxWidth: 'lg' }
+  const component = mount(BottomNav, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../types.js'
@@ -12,6 +23,19 @@
   // eslint-disable-next-line no-import-assign -- type re-export
   export type { BottomNavItem }
 
+  /**
+   * 底部导航的内容宽度预设；none 取消预设宽度约束。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { BottomNav } from '@h-ai/ui'
+   * const props: ComponentProps<typeof BottomNav> = { items: [{ id: 'home', label: '首页', iconClass: 'icon-[tabler--home]' }], active: 'home', maxWidth: 'lg' }
+   * const component = mount(BottomNav, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   type BottomNavMaxWidth = 'sm' | 'md' | 'lg' | 'xl' | 'none'
 
   const MAX_WIDTH_CLASS: Record<BottomNavMaxWidth, string> = {
@@ -22,6 +46,19 @@
     none: '',
   }
 
+  /**
+   * BottomNav 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { BottomNav } from '@h-ai/ui'
+   * const props: ComponentProps<typeof BottomNav> = { items: [{ id: 'home', label: '首页', iconClass: 'icon-[tabler--home]' }], active: 'home', maxWidth: 'lg' }
+   * const component = mount(BottomNav, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 导航项列表 */
     items: BottomNavItem[]

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

@@ -1,6 +1,32 @@
 import type { DataAttributes } from '../../types.js';
 import type { BottomNavItem } from './bottom-nav-types.js';
+/**
+ * 底部导航的内容宽度预设；none 取消预设宽度约束。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { BottomNav } from '@h-ai/ui'
+ * const props: ComponentProps<typeof BottomNav> = { items: [{ id: 'home', label: '首页', iconClass: 'icon-[tabler--home]' }], active: 'home', maxWidth: 'lg' }
+ * const component = mount(BottomNav, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 type BottomNavMaxWidth = 'sm' | 'md' | 'lg' | 'xl' | 'none';
+/**
+ * BottomNav 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { BottomNav } from '@h-ai/ui'
+ * const props: ComponentProps<typeof BottomNav> = { items: [{ id: 'home', label: '首页', iconClass: 'icon-[tabler--home]' }], active: 'home', maxWidth: 'lg' }
+ * const component = mount(BottomNav, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 导航项列表 */
     items: BottomNavItem[];
@@ -18,6 +44,23 @@ interface Props {
     class?: string;
 }
 type $$ComponentProps = Props & DataAttributes;
+/**
+ * BottomNav
+ * @h-ai/ui — BottomNav（底部导航栏）
+ *
+ * 用法：
+ * <BottomNav items={navItems} active="home" onchange={(id) => goto(`/${id}`)} />
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { BottomNav } from '@h-ai/ui'
+ * const props: ComponentProps<typeof BottomNav> = { items: [{ id: 'home', label: '首页', iconClass: 'icon-[tabler--home]' }], active: 'home', maxWidth: 'lg' }
+ * const component = mount(BottomNav, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const BottomNav: import("svelte").Component<$$ComponentProps, {
     BottomNavItem: typeof BottomNavItem;
 }, "">;

package/dist/components/compounds/Breadcrumb.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Breadcrumb
   =============================================================================
   @h-ai/ui - Breadcrumb 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Breadcrumb } from '@h-ai/ui'
+  const props: ComponentProps<typeof Breadcrumb> = { items: [{ label: '首页', href: '/' }, { label: '设置' }] }
+  const component = mount(Breadcrumb, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { BreadcrumbProps, DataAttributes } from '../../types.js'

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

@@ -1,5 +1,25 @@
 import type { BreadcrumbProps, DataAttributes } from '../../types.js';
 type $$ComponentProps = BreadcrumbProps & DataAttributes;
+/**
+ * Breadcrumb
+ * =============================================================================
+ * @h-ai/ui - Breadcrumb 组件
+ * =============================================================================
+ * 面包屑导航组件
+ *
+ * 使用 Svelte 5 Runes ($props)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Breadcrumb } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Breadcrumb> = { items: [{ label: '首页', href: '/' }, { label: '设置' }] }
+ * const component = mount(Breadcrumb, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Breadcrumb: import("svelte").Component<$$ComponentProps, {}, "">;
 type Breadcrumb = ReturnType<typeof Breadcrumb>;
 export default Breadcrumb;

package/dist/components/compounds/Calendar.svelte

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

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

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

package/dist/components/compounds/Card.svelte

@@ -1,6 +1,16 @@
 <!--
   @component Card
   卡片组件，默认使用 border 而非 shadow，更现代克制。
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Card } from '@h-ai/ui'
+  const props: ComponentProps<typeof Card> = { title: '个人资料', bordered: true, children: createRawSnippet(() => ({ render: () => "<span>资料内容</span>" })) }
+  const component = mount(Card, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { CardProps, DataAttributes } from '../../types.js'

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

@@ -3,6 +3,16 @@ type $$ComponentProps = CardProps & DataAttributes;
 /**
  * Card
  * 卡片组件，默认使用 border 而非 shadow，更现代克制。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Card } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Card> = { title: '个人资料', bordered: true, children: createRawSnippet(() => ({ render: () => "<span>资料内容</span>" })) }
+ * const component = mount(Card, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const Card: import("svelte").Component<$$ComponentProps, {}, "">;
 type Card = ReturnType<typeof Card>;

package/dist/components/compounds/Combobox.svelte

@@ -15,23 +15,15 @@
   @prop {string} class - 自定义类名
   @prop {function} onchange - 值变更回调
 
-  @example 单选
-  <Combobox
-    options={[
-      { value: 'svelte', label: 'Svelte' },
-      { value: 'react', label: 'React' },
-    ]}
-    bind:value={framework}
-    placeholder="搜索框架..."
-  />
-
-  @example 多选
-  <Combobox
-    options={skills}
-    bind:value={selectedSkills}
-    multiple
-    placeholder="搜索技能..."
-  />
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Combobox } from '@h-ai/ui'
+  const props: ComponentProps<typeof Combobox> = { options: [{ value: 'svelte', label: 'Svelte' }], value: 'svelte' }
+  const component = mount(Combobox, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, FormText, Size } from '../../types.js'
@@ -43,7 +35,19 @@
   import { getFormControlSizeClasses } from '../control-size.js'
   import BareButton from '../primitives/BareButton.svelte'
 
-  /** 选项定义 */
+  /**
+   * 选项定义
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { Combobox } from '@h-ai/ui'
+   * const props: ComponentProps<typeof Combobox> = { options: [{ value: 'svelte', label: 'Svelte' }], value: 'svelte' }
+   * const component = mount(Combobox, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Option {
     /** 选项值 */
     value: string
@@ -55,6 +59,19 @@
     description?: string
   }
 
+  /**
+   * Combobox 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { Combobox } from '@h-ai/ui'
+   * const props: ComponentProps<typeof Combobox> = { options: [{ value: 'svelte', label: 'Svelte' }], value: 'svelte' }
+   * const component = mount(Combobox, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 选项列表 */
     options: Option[]

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

@@ -1,6 +1,18 @@
 import type { DataAttributes, FormText, Size } from '../../types.js';
 import { Combobox } from 'bits-ui';
-/** 选项定义 */
+/**
+ * 选项定义
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Combobox } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Combobox> = { options: [{ value: 'svelte', label: 'Svelte' }], value: 'svelte' }
+ * const component = mount(Combobox, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Option {
     /** 选项值 */
     value: string;
@@ -11,6 +23,19 @@ interface Option {
     /** 描述文本（仅在多选模式下展示） */
     description?: string;
 }
+/**
+ * Combobox 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Combobox } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Combobox> = { options: [{ value: 'svelte', label: 'Svelte' }], value: 'svelte' }
+ * const component = mount(Combobox, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 选项列表 */
     options: Option[];
@@ -51,23 +76,15 @@ type $$ComponentProps = Props & DataAttributes;
  * @prop {string} class - 自定义类名
  * @prop {function} onchange - 值变更回调
  *
- * @example 单选
- * <Combobox
- *   options={[
- *     { value: 'svelte', label: 'Svelte' },
- *     { value: 'react', label: 'React' },
- *   ]}
- *   bind:value={framework}
- *   placeholder="搜索框架..."
- * />
- *
- * @example 多选
- * <Combobox
- *   options={skills}
- *   bind:value={selectedSkills}
- *   multiple
- *   placeholder="搜索技能..."
- * />
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Combobox } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Combobox> = { options: [{ value: 'svelte', label: 'Svelte' }], value: 'svelte' }
+ * const component = mount(Combobox, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const Combobox: import("svelte").Component<$$ComponentProps, {}, "value">;
 type Combobox = ReturnType<typeof Combobox>;

package/dist/components/compounds/Confirm.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Confirm
   =============================================================================
   @h-ai/ui - Confirm 组件
   =============================================================================
@@ -7,6 +8,16 @@
   使用 Svelte 5 Runes ($props, $state)
   使用 primitives 组件：Button
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Confirm } from '@h-ai/ui'
+  const props: ComponentProps<typeof Confirm> = { open: true, title: '删除记录', message: '确定删除这条记录？', variant: 'warning' }
+  const component = mount(Confirm, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { ConfirmProps, DataAttributes } from '../../types.js'

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

@@ -1,5 +1,26 @@
 import type { ConfirmProps, DataAttributes } from '../../types.js';
 type $$ComponentProps = ConfirmProps & DataAttributes;
+/**
+ * Confirm
+ * =============================================================================
+ * @h-ai/ui - Confirm 组件
+ * =============================================================================
+ * 确认对话框组件
+ *
+ * 使用 Svelte 5 Runes ($props, $state)
+ * 使用 primitives 组件：Button
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Confirm } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Confirm> = { open: true, title: '删除记录', message: '确定删除这条记录？', variant: 'warning' }
+ * const component = mount(Confirm, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Confirm: import("svelte").Component<$$ComponentProps, {}, "open">;
 type Confirm = ReturnType<typeof Confirm>;
 export default Confirm;