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

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

@@ -1,5 +1,18 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../types.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';
@@ -9,6 +22,25 @@ interface Props {
     children: Snippet;
 }
 type $$ComponentProps = Props & DataAttributes;
+/**
+ * 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)
+ * ```
+ */
 declare const SafeArea: import("svelte").Component<$$ComponentProps, {}, "">;
 type SafeArea = ReturnType<typeof SafeArea>;
 export default SafeArea;

package/dist/components/compounds/Skeleton.svelte

@@ -1,6 +1,16 @@
 <!--
   @component Skeleton
   骨架屏占位组件，用于加载状态展示。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Skeleton } from '@h-ai/ui'
+  const props: ComponentProps<typeof Skeleton> = { variant: 'text', count: 3 }
+  const component = mount(Skeleton, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, SkeletonProps } from '../../types.js'

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

@@ -3,6 +3,16 @@ type $$ComponentProps = SkeletonProps & DataAttributes;
 /**
  * Skeleton
  * 骨架屏占位组件，用于加载状态展示。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Skeleton } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Skeleton> = { variant: 'text', count: 3 }
+ * const component = mount(Skeleton, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const Skeleton: import("svelte").Component<$$ComponentProps, {}, "">;
 type Skeleton = ReturnType<typeof Skeleton>;

package/dist/components/compounds/Steps.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component Steps
   =============================================================================
   @h-ai/ui - Steps 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $derived)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Steps } from '@h-ai/ui'
+  const props: ComponentProps<typeof Steps> = { items: [{ title: '填写资料' }, { title: '确认' }], current: 0 }
+  const component = mount(Steps, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, StepsProps } from '../../types.js'

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

@@ -1,5 +1,25 @@
 import type { DataAttributes, StepsProps } from '../../types.js';
 type $$ComponentProps = StepsProps & DataAttributes;
+/**
+ * Steps
+ * =============================================================================
+ * @h-ai/ui - Steps 组件
+ * =============================================================================
+ * 步骤条组件
+ *
+ * 使用 Svelte 5 Runes ($props, $derived)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Steps } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Steps> = { items: [{ title: '填写资料' }, { title: '确认' }], current: 0 }
+ * const component = mount(Steps, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const Steps: import("svelte").Component<$$ComponentProps, {}, "">;
 type Steps = ReturnType<typeof Steps>;
 export default Steps;

package/dist/components/compounds/SwipeCell.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component SwipeCell
   @h-ai/ui — SwipeCell（滑动操作 — 列表项左滑删除等）
 
   用法：
@@ -10,6 +11,16 @@
   >
     <div class="p-4">列表项内容</div>
   </SwipeCell>
+
+  @example
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { SwipeCell } from '@h-ai/ui'
+  const props: ComponentProps<typeof SwipeCell> = { actions: [{ id: 'remove', label: '删除', variant: 'error' }], children: createRawSnippet(() => ({ render: () => "<p>向左滑动显示操作。</p>" })) }
+  const component = mount(SwipeCell, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'
@@ -20,6 +31,19 @@
   // eslint-disable-next-line no-import-assign -- type re-export
   export type { SwipeCellAction }
 
+  /**
+   * SwipeCell 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount, createRawSnippet } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { SwipeCell } from '@h-ai/ui'
+   * const props: ComponentProps<typeof SwipeCell> = { actions: [{ id: 'remove', label: '删除', variant: 'error' }], children: createRawSnippet(() => ({ render: () => "<p>向左滑动显示操作。</p>" })) }
+   * const component = mount(SwipeCell, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 右侧操作列表 */
     actions: SwipeCellAction[]

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

@@ -1,6 +1,19 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../types.js';
 import type { SwipeCellAction } from './swipe-cell-types.js';
+/**
+ * SwipeCell 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { SwipeCell } from '@h-ai/ui'
+ * const props: ComponentProps<typeof SwipeCell> = { actions: [{ id: 'remove', label: '删除', variant: 'error' }], children: createRawSnippet(() => ({ render: () => "<p>向左滑动显示操作。</p>" })) }
+ * const component = mount(SwipeCell, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 右侧操作列表 */
     actions: SwipeCellAction[];
@@ -14,6 +27,30 @@ interface Props {
     children: Snippet;
 }
 type $$ComponentProps = Props & DataAttributes;
+/**
+ * SwipeCell
+ * @h-ai/ui — SwipeCell（滑动操作 — 列表项左滑删除等）
+ *
+ * 用法：
+ * <SwipeCell
+ *   actions={[
+ *     { id: 'delete', label: '删除', variant: 'error' },
+ *   ]}
+ *   onaction={(id) => handleAction(id)}
+ * >
+ *   <div class="p-4">列表项内容</div>
+ * </SwipeCell>
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { SwipeCell } from '@h-ai/ui'
+ * const props: ComponentProps<typeof SwipeCell> = { actions: [{ id: 'remove', label: '删除', variant: 'error' }], children: createRawSnippet(() => ({ render: () => "<p>向左滑动显示操作。</p>" })) }
+ * const component = mount(SwipeCell, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const SwipeCell: import("svelte").Component<$$ComponentProps, {
     SwipeCellAction: typeof SwipeCellAction;
 }, "">;

package/dist/components/compounds/TableToolbar.svelte

@@ -25,23 +25,14 @@
   @prop {Function} onPrimaryAction - 主操作回调
 
   @example
-  <TableToolbar
-    searchable
-    searchPlaceholder="搜索..."
-    bind:searchValue
-    filterFields={[
-      { id: 'status', label: '状态', type: 'enum', options: [{ label: '启用', value: 'active' }] }
-    ]}
-    bind:filterValues
-    sortableColumns={[{ key: 'name', label: '名称' }]}
-    sortBy="name"
-    sortDirection="asc"
-    onsearch={(v) => handleSearch(v)}
-    onfilterchange={(f) => handleFilter(f)}
-    onsort={(key, dir) => handleSort(key, dir)}
-  >
-    <Button size="sm" onclick={handleExport}>导出</Button>
-  </TableToolbar>
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { TableToolbar } from '@h-ai/ui'
+  const props: ComponentProps<typeof TableToolbar> = { searchable: true, searchValue: 'Ada', filterFields: [{ id: 'active', label: '状态', type: 'boolean' }] }
+  const component = mount(TableToolbar, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'
@@ -50,7 +41,14 @@
   import { uiM } from '../../messages.js'
   import { getDataAttributes } from '../../utils.js'
 
-  /** 工具栏筛选字段定义。 */
+  /**
+   * 工具栏筛选字段定义。
+   *
+   * @example 模块内部上下文
+   * ```ts
+   * const example: FilterFieldDef = { id: 'active', label: '状态', type: 'boolean' }
+   * ```
+   */
   type FilterFieldDef = {
     /** 筛选字段 key，同时作为回调中的属性名。 */
     id: string
@@ -74,7 +72,19 @@
     options?: Array<{ label: string, value: string | number | boolean }> | (() => Array<{ label: string, value: string | number | boolean }>)
   }
 
-  /** TableToolbar 对外入参。 */
+  /**
+   * TableToolbar 对外入参。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { TableToolbar } from '@h-ai/ui'
+   * const props: ComponentProps<typeof TableToolbar> = { searchable: true, searchValue: 'Ada', filterFields: [{ id: 'active', label: '状态', type: 'boolean' }] }
+   * const component = mount(TableToolbar, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   type TableToolbarProps = {
     /** 是否显示搜索框，默认 true。 */
     searchable?: boolean
@@ -158,6 +168,19 @@
   let sortOpen = $state(false)
   /** 用于检测外部点击的根节点。 */
   let rootElement = $state<HTMLElement | null>(null)
+  let filterTrigger = $state<HTMLButtonElement>()
+  let sortTrigger = $state<HTMLButtonElement>()
+  let filterPanel = $state<HTMLDivElement>()
+  let sortPanel = $state<HTMLDivElement>()
+  const toolbarId = $props.id()
+
+  // 弹层渲染后直接进入可用输入；关闭与外部点击不抢夺其它控件焦点。
+  $effect(() => {
+    const panel = filterOpen ? filterPanel : sortOpen ? sortPanel : undefined
+    const control = panel?.querySelector<HTMLElement>('input:not(:disabled), select:not(:disabled)')
+      ?? panel?.querySelector<HTMLElement>('button:not(:disabled)')
+    control?.focus()
+  })
 
   // ─── 日期范围本地输入 ───
   /** 日期范围起始输入框草稿。 */
@@ -373,23 +396,28 @@
 
     /** Escape 键关闭当前弹层。 */
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
+      if (event.key === 'Escape' && !event.defaultPrevented && (filterOpen || sortOpen)) {
+        event.preventDefault()
+        event.stopPropagation()
+        const trigger = filterOpen ? filterTrigger : sortTrigger
         filterOpen = false
         sortOpen = false
+        trigger?.focus()
       }
     }
 
     document.addEventListener('pointerdown', handlePointerDown)
-    document.addEventListener('keydown', handleKeyDown)
+    const root = rootElement
+    root?.addEventListener('keydown', handleKeyDown)
 
     return () => {
       document.removeEventListener('pointerdown', handlePointerDown)
-      document.removeEventListener('keydown', handleKeyDown)
+      root?.removeEventListener('keydown', handleKeyDown)
     }
   })
 </script>
 
-<div {...dataAttributes} bind:this={rootElement} class='flex items-center justify-between gap-3 flex-wrap {className}'>
+<div {...dataAttributes} bind:this={rootElement} class='relative flex min-w-0 w-full items-center justify-between gap-3 flex-wrap {className}'>
   <!-- 左侧信息区：标题、说明等不参与表格操作的内容。 -->
   {#if leading}
     <div class='min-w-0 flex-1'>
@@ -421,13 +449,15 @@
 
     <!-- 筛选弹层按钮 -->
     {#if hasFilters}
-      <div class='relative'>
+      <div>
         <button
+          bind:this={filterTrigger}
           type='button'
           aria-expanded={filterOpen}
+          aria-controls={filterOpen ? `${toolbarId}-filters` : undefined}
           aria-haspopup='dialog'
           aria-label={uiM('toolbar_filter')}
-          class='btn btn-sm btn-square border-base-content/15 bg-base-100 {activeFilterCount > 0 ? 'border-primary/50 text-primary bg-primary/5' : ''}'
+          class='relative btn btn-sm btn-square border-base-content/15 bg-base-100 {activeFilterCount > 0 ? 'border-primary/50 text-primary bg-primary/5' : ''}'
           title={uiM('toolbar_filter')}
           onclick={toggleFilterPopover}
         >
@@ -441,9 +471,11 @@
 
         {#if filterOpen}
           <div
+            bind:this={filterPanel}
+            id={`${toolbarId}-filters`}
             role='dialog'
             aria-label={uiM('toolbar_filter_conditions')}
-            class='absolute top-full right-0 mt-2 z-50 w-[min(22rem,calc(100vw-2rem))] rounded-xl border border-base-content/10 bg-base-100 p-4 shadow-lg'
+            class='absolute top-full right-0 mt-2 z-50 w-[min(22rem,100%,calc(100vw-2rem))] max-h-[60vh] overflow-y-auto rounded-xl border border-base-content/10 bg-base-100 p-4 shadow-lg'
           >
             <div class='flex items-center justify-between mb-3'>
               <h3 class='text-sm font-semibold text-base-content'>{uiM('toolbar_filter')}</h3>
@@ -555,10 +587,12 @@
 
     <!-- 排序弹层按钮 -->
     {#if hasSortableColumns}
-      <div class='relative'>
+      <div>
         <button
+          bind:this={sortTrigger}
           type='button'
           aria-expanded={sortOpen}
+          aria-controls={sortOpen ? `${toolbarId}-sort` : undefined}
           aria-haspopup='dialog'
           aria-label={uiM('toolbar_sort')}
           class='btn btn-sm btn-square border-base-content/15 bg-base-100 {sortBy ? 'border-primary/50 text-primary bg-primary/5' : ''}'
@@ -570,9 +604,11 @@
 
         {#if sortOpen}
           <div
+            bind:this={sortPanel}
+            id={`${toolbarId}-sort`}
             role='dialog'
             aria-label={uiM('toolbar_sort_conditions')}
-            class='absolute top-full right-0 mt-2 z-50 w-[min(18rem,calc(100vw-2rem))] rounded-xl border border-base-content/10 bg-base-100 p-4 shadow-lg'
+            class='absolute top-full right-0 mt-2 z-50 w-[min(18rem,100%,calc(100vw-2rem))] max-h-[60vh] overflow-y-auto rounded-xl border border-base-content/10 bg-base-100 p-4 shadow-lg'
           >
             <div class='flex items-center justify-between mb-3'>
               <h3 class='text-sm font-semibold text-base-content'>{uiM('toolbar_sort')}</h3>
@@ -652,6 +688,7 @@
           type='button'
           class='btn btn-sm join-item border-base-content/15 bg-base-100 {viewMode === 'table' ? 'text-primary bg-primary/5' : ''}'
           aria-label={uiM('toolbar_view_table')}
+          aria-pressed={viewMode === 'table'}
           title={uiM('toolbar_view_table')}
           onclick={() => {
             viewMode = 'table'
@@ -664,6 +701,7 @@
           type='button'
           class='btn btn-sm join-item border-base-content/15 bg-base-100 {viewMode === 'card' ? 'text-primary bg-primary/5' : ''}'
           aria-label={uiM('toolbar_view_card')}
+          aria-pressed={viewMode === 'card'}
           title={uiM('toolbar_view_card')}
           onclick={() => {
             viewMode = 'card'

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

@@ -1,6 +1,13 @@
 import type { Snippet } from 'svelte';
 import type { DataAttributes } from '../../types.js';
-/** 工具栏筛选字段定义。 */
+/**
+ * 工具栏筛选字段定义。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const example: FilterFieldDef = { id: 'active', label: '状态', type: 'boolean' }
+ * ```
+ */
 type FilterFieldDef = {
     /** 筛选字段 key，同时作为回调中的属性名。 */
     id: string;
@@ -29,7 +36,19 @@ type FilterFieldDef = {
         value: string | number | boolean;
     }>);
 };
-/** TableToolbar 对外入参。 */
+/**
+ * TableToolbar 对外入参。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { TableToolbar } from '@h-ai/ui'
+ * const props: ComponentProps<typeof TableToolbar> = { searchable: true, searchValue: 'Ada', filterFields: [{ id: 'active', label: '状态', type: 'boolean' }] }
+ * const component = mount(TableToolbar, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 type TableToolbarProps = {
     /** 是否显示搜索框，默认 true。 */
     searchable?: boolean;
@@ -106,23 +125,14 @@ type TableToolbarProps = {
  * @prop {Function} onPrimaryAction - 主操作回调
  *
  * @example
- * <TableToolbar
- *   searchable
- *   searchPlaceholder="搜索..."
- *   bind:searchValue
- *   filterFields={[
- *     { id: 'status', label: '状态', type: 'enum', options: [{ label: '启用', value: 'active' }] }
- *   ]}
- *   bind:filterValues
- *   sortableColumns={[{ key: 'name', label: '名称' }]}
- *   sortBy="name"
- *   sortDirection="asc"
- *   onsearch={(v) => handleSearch(v)}
- *   onfilterchange={(f) => handleFilter(f)}
- *   onsort={(key, dir) => handleSort(key, dir)}
- * >
- *   <Button size="sm" onclick={handleExport}>导出</Button>
- * </TableToolbar>
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { TableToolbar } from '@h-ai/ui'
+ * const props: ComponentProps<typeof TableToolbar> = { searchable: true, searchValue: 'Ada', filterFields: [{ id: 'active', label: '状态', type: 'boolean' }] }
+ * const component = mount(TableToolbar, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const TableToolbar: import("svelte").Component<TableToolbarProps, {}, "searchValue" | "filterValues" | "sortBy" | "sortDirection" | "viewMode">;
 type TableToolbar = ReturnType<typeof TableToolbar>;

package/dist/components/compounds/Tabs.svelte

@@ -1,12 +1,21 @@
 <!--
   @component Tabs
   标签页组件，支持 line/card/pills 三种样式。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { Tabs } from '@h-ai/ui'
+  const props: ComponentProps<typeof Tabs> = { items: [{ key: 'profile', label: '资料' }, { key: 'security', label: '安全' }], active: 'profile', lazy: true }
+  const component = mount(Tabs, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, TabsProps } from '../../types.js'
   import { SvelteSet } from 'svelte/reactivity'
   import { cn, getDataAttributes } from '../../utils.js'
-  import BareButton from '../primitives/BareButton.svelte'
 
   let {
     items,
@@ -22,13 +31,15 @@
   }: TabsProps & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
+  const tabsId = $props.id()
+  let tablist = $state<HTMLDivElement>()
   // 已激活过的页签集合，用于惰性挂载（不预加载不可见页签）。
   const activatedKeys = new SvelteSet<string>()
 
-  // 默认选中第一个
+  // 初始或选项变化后选中可用页签，避免激活禁用项或已删除项。
   $effect(() => {
-    if (!active && items.length > 0) {
-      active = items[0].key
+    if (!items.some(item => item.key === active && !item.disabled)) {
+      active = items.find(item => !item.disabled)?.key ?? ''
     }
   })
 
@@ -65,6 +76,7 @@
   const tabsClass = $derived(
     cn(
       'tabs',
+      'max-w-full flex-nowrap overflow-x-auto',
       typeMap[type],
       sizeMap[size],
       className,
@@ -72,30 +84,66 @@
   )
 
   function handleSelect(key: string) {
+    if (active === key)
+      return
     active = key
     onchange?.(key)
   }
+
+  // 自动激活模式：方向键移动焦点并选择，跳过禁用项且支持首尾循环。
+  function handleKeydown(event: KeyboardEvent, key: string) {
+    const enabled = items.filter(item => !item.disabled)
+    if (!enabled.length)
+      return
+    const index = enabled.findIndex(item => item.key === key)
+    const rtl = getComputedStyle(event.currentTarget as HTMLElement).direction === 'rtl'
+    let next: number
+    switch (event.key) {
+      case 'ArrowRight':
+        next = index + (rtl ? -1 : 1)
+        break
+      case 'ArrowLeft':
+        next = index + (rtl ? 1 : -1)
+        break
+      case 'Home':
+        next = 0
+        break
+      case 'End':
+        next = enabled.length - 1
+        break
+      default: return
+    }
+    event.preventDefault()
+    const selected = enabled[(next + enabled.length) % enabled.length]
+    handleSelect(selected.key)
+    tablist?.querySelectorAll<HTMLButtonElement>('[role="tab"]:not(:disabled)')[(next + enabled.length) % enabled.length]?.focus()
+  }
 </script>
 
-<div {...dataAttributes} role='tablist' class={tabsClass}>
+<div {...dataAttributes} bind:this={tablist} role='tablist' class={tabsClass}>
   {#each items as item (item.key)}
-    <BareButton
+    <button
+      type='button'
+      id={`${tabsId}-${encodeURIComponent(item.key)}`}
       role='tab'
-      ariaSelected={active === item.key}
-      class={cn('tab', active === item.key && 'tab-active')}
+      aria-selected={active === item.key}
+      aria-controls={children ? `${tabsId}-panel` : undefined}
+      tabindex={active === item.key ? 0 : -1}
+      class={cn('tab shrink-0', active === item.key && 'tab-active')}
       disabled={item.disabled}
       onclick={() => handleSelect(item.key)}
+      onkeydown={event => handleKeydown(event, item.key)}
     >
       {#if item.icon}
         <span class='mr-1'>{item.icon}</span>
       {/if}
       {item.label}
-    </BareButton>
+    </button>
   {/each}
 </div>
 
 {#if children}
-  <div class='py-4'>
+  <div id={`${tabsId}-panel`} role='tabpanel' aria-labelledby={active ? `${tabsId}-${encodeURIComponent(active)}` : undefined} tabindex='0' class='min-w-0 py-4'>
     {@render children({ active, isActivated })}
   </div>
 {/if}

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

@@ -3,6 +3,16 @@ type $$ComponentProps = TabsProps & DataAttributes;
 /**
  * Tabs
  * 标签页组件，支持 line/card/pills 三种样式。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { Tabs } from '@h-ai/ui'
+ * const props: ComponentProps<typeof Tabs> = { items: [{ key: 'profile', label: '资料' }, { key: 'security', label: '安全' }], active: 'profile', lazy: true }
+ * const component = mount(Tabs, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const Tabs: import("svelte").Component<$$ComponentProps, {}, "active">;
 type Tabs = ReturnType<typeof Tabs>;

package/dist/components/compounds/TagInput.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component TagInput
   =============================================================================
   @h-ai/ui - TagInput 组件
   =============================================================================
@@ -6,6 +7,16 @@
 
   使用 Svelte 5 Runes ($props, $state, $bindable)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { TagInput } from '@h-ai/ui'
+  const props: ComponentProps<typeof TagInput> = { tags: ['Svelte'], maxTags: 5 }
+  const component = mount(TagInput, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, TagInputProps } from '../../types.js'

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

@@ -1,5 +1,25 @@
 import type { DataAttributes, TagInputProps } from '../../types.js';
 type $$ComponentProps = TagInputProps & DataAttributes;
+/**
+ * TagInput
+ * =============================================================================
+ * @h-ai/ui - TagInput 组件
+ * =============================================================================
+ * 标签输入框组件
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $bindable)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { TagInput } from '@h-ai/ui'
+ * const props: ComponentProps<typeof TagInput> = { tags: ['Svelte'], maxTags: 5 }
+ * const component = mount(TagInput, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const TagInput: import("svelte").Component<$$ComponentProps, {}, "tags">;
 type TagInput = ReturnType<typeof TagInput>;
 export default TagInput;