@h-ai/ui 0.1.0-alpha.57 → 0.1.0-alpha.58

package/README.en.md

@@ -98,6 +98,16 @@ With auto-import enabled, use components directly in templates without individua
 
 > `@h-ai/ui/auto-import` injects all public Svelte components except `toast`, type imports, and `Range` (which conflicts with the DOM `Range` constructor).
 
+Pages using a subset of components, such as administration screens, can import public component-directory entry points directly. Import theme utilities from the lightweight `@h-ai/ui/theme` entry so theme consumers do not load the root entry's AI and chart components. Check the installed package's exports; do not import its internal `src/` or `dist/` paths.
+
+The preprocessor recognizes semicolon-free, multiline and aliased imports without injecting components already bound locally. Type-only imports do not replace runtime components.
+
+```ts
+import { Card } from '@h-ai/ui/components/compounds/index'
+import { Button } from '@h-ai/ui/components/primitives/index'
+import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
+```
+
 ### data-\* attribute forwarding
 
 Public Svelte components forward caller-supplied `data-*` attributes to their root or primary interactive element for tests, analytics, and automation. Other unknown attributes are not forwarded.
@@ -154,6 +164,8 @@ components/
 | `Spinner`        | Loading animation   | `size`, `variant`                                                              |
 | `Progress`       | Progress bar        | `value`, `max`, `variant`, `striped`, `animated`                               |
 
+For `BareInput` with `type="file"`, read `event.currentTarget.files` in `onchange` and leave the file path `value` unbound. Other input types support `bind:value`.
+
 ### Compounds (36)
 
 #### Forms
@@ -175,7 +187,7 @@ components/
 
 | Component | Description         | Key props                                                                    |
 | --------- | ------------------- | ---------------------------------------------------------------------------- |
-| `Modal`   | Modal               | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose`               |
+| `Modal`   | Modal with dialog semantics, focus trap and restoration | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose`               |
 | `Drawer`  | Drawer              | `open`, `position`, `title`, `size`, `width`, `resizable`, `widthStorageKey` |
 | `Confirm` | Confirmation dialog | `open`, `title`, `message`, `variant`, `onconfirm`                           |
 | `Popover` | Popover             | `open`, `position`, `trigger`, `offset`, `portal`                            |
@@ -262,7 +274,7 @@ components/
 | `ChangePasswordForm` | Change password                                  | `loading`, `errors`, `requireOldPassword`, `onsubmit`                                                  |
 | `PasswordInput`      | Password input                                   | `value`, `showToggle`, `showStrength`, `minLength`                                                     |
 | `PermGuard`          | Permission guard                                 | `permissions`, `mode`, `fallback`                                                                      |
-| `UserProfile`        | User profile                                     | `user`, `editable`, `fields`, `onsubmit`                                                               |
+| `UserProfile`        | User profile                                     | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
 
 #### Storage (4)
 
@@ -628,13 +640,14 @@ import {
   applyTheme, // 应用主题（自动持久化到 localStorage）
   createThemeBootstrapScript, // 生成可注入 app.html 的首屏主题恢复脚本
   getCurrentTheme, // 获取当前主题
+  getSavedTheme, // Read saved appearance, with an optional application default
   getThemeInitScript, // 返回可注入到 HTML shell 的防闪烁脚本文本
   isDarkTheme, // 检查是否暗色主题
   normalizeHexColor, // 归一化 #RGB / #RRGGBB 主题色
   normalizeThemeId, // 校验主题 ID 并自动回退
   THEME_GROUPS, // 按亮色/暗色分组
   THEMES, // ThemeInfo[] — 15 个精选主题元数据
-} from '@h-ai/ui'
+} from '@h-ai/ui/theme'
 ```
 
 Use `getThemeInitScript()` for simple cases. For custom storage keys, theme color CSS variables, or language preferences, generate `createThemeBootstrapScript()` on the server and inject it into `app.html`.
@@ -650,7 +663,7 @@ Place a placeholder in SvelteKit `app.html`:
 Then inject it from `hooks.server.ts`:
 
 ```ts
-import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui'
+import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui/theme'
 
 const themeBootstrapScript = createThemeBootstrapScript({
   storageKey: 'hai-demo-preferences',

package/README.ja.md

@@ -98,6 +98,16 @@ export default defineConfig({
 
 > `toast`・型 import・DOM の `Range` と衝突する `Range` を除き、公開 Svelte コンポーネントは `@h-ai/ui/auto-import` で自動注入できます。
 
+管理画面など一部のコンポーネントを使うページは、公開コンポーネントディレクトリーの入口から直接 import できます。テーマツールは軽量な `@h-ai/ui/theme` から読み込み、テーマの利用だけでルート入口の AI・グラフコンポーネントを読み込まないようにします。インストール済みパッケージの exports を確認し、内部 `src/`・`dist/` は import しないでください。
+
+自動 import はセミコロンなし、複数行、別名の import を認識し、既存のローカル名を重複注入しません。型のみの import は実行時コンポーネントの代わりにはなりません。
+
+```ts
+import { Card } from '@h-ai/ui/components/compounds/index'
+import { Button } from '@h-ai/ui/components/primitives/index'
+import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
+```
+
 ### data-\* 属性の転送
 
 公開 Svelte コンポーネントは `data-*` をルート・主操作要素へ転送し、テスト・計測・自動化に使えます。通常の未知属性は転送しません。
@@ -154,6 +164,8 @@ components/
 | `Spinner`        | 読み込み表示           | `size`, `variant`                                                              |
 | `Progress`       | プログレスバー         | `value`, `max`, `variant`, `striped`, `animated`                               |
 
+`BareInput` の `type="file"` では `onchange` の `event.currentTarget.files` を読み取り、ファイルパスの `value` はバインドしません。他の入力型では `bind:value` を使用できます。
+
 ### Compounds：複合コンポーネント（36）
 
 #### フォーム
@@ -175,7 +187,7 @@ components/
 
 | コンポーネント | 説明           | 主なプロパティ                                                               |
 | -------------- | -------------- | ---------------------------------------------------------------------------- |
-| `Modal`        | モーダル       | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose`               |
+| `Modal`        | モーダル（ダイアログ属性・フォーカス制御と復元） | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose`               |
 | `Drawer`       | ドロワー       | `open`, `position`, `title`, `size`, `width`, `resizable`, `widthStorageKey` |
 | `Confirm`      | 確認ダイアログ | `open`, `title`, `message`, `variant`, `onconfirm`                           |
 | `Popover`      | ポップオーバー | `open`, `position`, `trigger`, `offset`, `portal`                            |
@@ -262,7 +274,7 @@ components/
 | `ChangePasswordForm` | パスワード変更                          | `loading`, `errors`, `requireOldPassword`, `onsubmit`                                                  |
 | `PasswordInput`      | パスワード入力                          | `value`, `showToggle`, `showStrength`, `minLength`                                                     |
 | `PermGuard`          | 権限ガード                              | `permissions`, `mode`, `fallback`                                                                      |
-| `UserProfile`        | ユーザープロフィール                    | `user`, `editable`, `fields`, `onsubmit`                                                               |
+| `UserProfile`        | ユーザープロフィール                    | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
 
 #### Storage：ストレージ（4）
 
@@ -628,13 +640,14 @@ import {
   applyTheme, // 应用主题（自动持久化到 localStorage）
   createThemeBootstrapScript, // 生成可注入 app.html 的首屏主题恢复脚本
   getCurrentTheme, // 获取当前主题
+  getSavedTheme, // 保存済みテーマ。アプリ既定値を指定可能
   getThemeInitScript, // 返回可注入到 HTML shell 的防闪烁脚本文本
   isDarkTheme, // 检查是否暗色主题
   normalizeHexColor, // 归一化 #RGB / #RRGGBB 主题色
   normalizeThemeId, // 校验主题 ID 并自动回退
   THEME_GROUPS, // 按亮色/暗色分组
   THEMES, // ThemeInfo[] — 15 个精选主题元数据
-} from '@h-ai/ui'
+} from '@h-ai/ui/theme'
 ```
 
 単純な場合は `getThemeInitScript()` を使えます。独自ストレージ key・テーマカラーの CSS 変数・言語設定がある場合、サーバーの `createThemeBootstrapScript()` で生成して `app.html` に注入することを推奨します。
@@ -650,7 +663,7 @@ SvelteKit の `app.html` にプレースホルダーを置きます：
 次に `hooks.server.ts` で注入します：
 
 ```ts
-import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui'
+import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui/theme'
 
 const themeBootstrapScript = createThemeBootstrapScript({
   storageKey: 'hai-demo-preferences',

package/README.md

@@ -98,6 +98,16 @@ export default defineConfig({
 
 > 除 `toast`、类型导入与 `Range`（会和 DOM `Range` 构造器冲突）外，其余公开 Svelte 组件都可通过 `@h-ai/ui/auto-import` 自动注入。
 
+管理后台等只使用部分组件的页面，可直接使用公开组件目录入口；主题工具通过轻量 `@h-ai/ui/theme` 导入，避免主题消费加载根入口中的 AI、图表等组件。组件路径以已安装版本的 exports 为准，不导入包内 `src/` 或 `dist/`。
+
+自动导入器识别无分号、跨行及带别名的显式导入，已绑定的组件名称不会重复注入；仅类型导入不会替代运行时组件。
+
+```ts
+import { Card } from '@h-ai/ui/components/compounds/index'
+import { Button } from '@h-ai/ui/components/primitives/index'
+import { getThemeInfo, THEMES } from '@h-ai/ui/theme'
+```
+
 ### data-* 属性透传
 
 公开 Svelte 组件支持把调用方传入的 `data-*` 属性透传到组件根节点或主交互节点，便于测试选择器、埋点和自动化标记。普通未知属性不会被透传。
@@ -154,6 +164,8 @@ components/
 | `Spinner`        | 加载动画     | `size`, `variant`                                                  |
 | `Progress`       | 进度条       | `value`, `max`, `variant`, `striped`, `animated`                   |
 
+`BareInput` 的 `file` 类型通过 `onchange` 读取 `event.currentTarget.files`，不绑定文件路径 `value`；其他输入类型可使用 `bind:value`。
+
 ### 组合组件 Compounds（36 个）
 
 #### 表单
@@ -175,7 +187,7 @@ components/
 
 | 组件      | 描述   | 主要属性                                                |
 | --------- | ------ | ------------------------------------------------------- |
-| `Modal`   | 模态框 | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose` |
+| `Modal`   | 模态框（语义标签、焦点约束与恢复） | `open`, `title`, `size`, `radius`, `bodyOverflow`, `showClose` |
 | `Drawer`  | 抽屉   | `open`, `position`, `title`, `size`, `width`, `resizable`, `widthStorageKey` |
 | `Confirm` | 确认框 | `open`, `title`, `message`, `variant`, `onconfirm`      |
 | `Popover` | 弹出层 | `open`, `position`, `trigger`, `offset`, `portal`       |
@@ -262,7 +274,7 @@ components/
 | `ChangePasswordForm` | 修改密码   | `loading`, `errors`, `requireOldPassword`, `onsubmit` |
 | `PasswordInput`      | 密码输入框 | `value`, `showToggle`, `showStrength`, `minLength`    |
 | `PermGuard`          | 权限守卫   | `permissions`, `mode`, `fallback`                     |
-| `UserProfile`        | 用户资料   | `user`, `editable`, `fields`, `onsubmit`              |
+| `UserProfile`        | 用户资料   | `user`, `editable`, `fields`, `avatarAccept`, `avatarHint`, `onsubmit` |
 
 #### Storage 存储（4 个）
 
@@ -627,13 +639,14 @@ import {
   applyTheme, // 应用主题（自动持久化到 localStorage）
   createThemeBootstrapScript, // 生成可注入 app.html 的首屏主题恢复脚本
   getCurrentTheme, // 获取当前主题
+  getSavedTheme, // 读取安全缓存，可传入应用配置的默认主题
   getThemeInitScript, // 返回可注入到 HTML shell 的防闪烁脚本文本
   isDarkTheme, // 检查是否暗色主题
   normalizeHexColor, // 归一化 #RGB / #RRGGBB 主题色
   normalizeThemeId, // 校验主题 ID 并自动回退
   THEME_GROUPS, // 按亮色/暗色分组
   THEMES, // ThemeInfo[] — 15 个精选主题元数据
-} from '@h-ai/ui'
+} from '@h-ai/ui/theme'
 ```
 
 简单场景可以直接使用 `getThemeInitScript()`；如果应用有自定义存储 key、主题色 CSS 变量或语言偏好，推荐在服务端通过 `createThemeBootstrapScript()` 生成脚本后再注入 `app.html`。
@@ -649,7 +662,7 @@ import {
 然后在 `hooks.server.ts` 里注入：
 
 ```ts
-import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui'
+import { createThemeBootstrapScript, DEFAULT_THEME_COLOR_CSS_VAR } from '@h-ai/ui/theme'
 
 const themeBootstrapScript = createThemeBootstrapScript({
   storageKey: 'hai-demo-preferences',

package/auto-import.js

@@ -7,6 +7,8 @@
  * =============================================================================
  */
 
+import { parse } from 'svelte/compiler'
+
 const UI_COMPONENTS = new Set([
   // primitives
   'Avatar',
@@ -112,10 +114,8 @@ const UI_COMPONENTS = new Set([
 const TAG_REGEX = /<([A-Z][A-Za-z0-9]*)\b/g
 const SCRIPT_REGEX = /<script\b([^>]*)>([\s\S]*?)<\/script>/g
 const UI_IMPORT_REGEX = /import\s*\{([^}]+)\}\s*from\s*['"]@h-ai\/ui['"];?/
-const IMPORT_ALIAS_SPLIT_REGEX = /\s+as\s+/i
 const WINDOWS_PATH_SEPARATOR_REGEX = /\\/g
 const MODULE_CONTEXT_ATTR_REGEX = /context\s*=\s*['"]module['"]/i
-const TYPE_IMPORT_PREFIX_REGEX = /^type\s+/
 
 function collectUsedComponents(content) {
   const used = new Set()
@@ -130,73 +130,16 @@ function collectUsedComponents(content) {
 
 function collectImportedNames(scriptContent) {
   const imported = new Set()
-  const lines = scriptContent.split('\n')
-  let buffer = ''
-
-  const flushImport = (statement) => {
-    const fromIndex = statement.lastIndexOf(' from ')
-    if (fromIndex === -1)
-      return
-
-    let clause = statement.slice('import '.length, fromIndex).trim()
-    clause = clause.replace(TYPE_IMPORT_PREFIX_REGEX, '')
-    if (!clause)
-      return
-
-    // default + named: Button, { Input as UiInput }
-    if (clause.includes('{')) {
-      const [defaultPart, namedPart] = clause.split('{')
-      const defaultName = defaultPart.replace(',', '').trim()
-      if (defaultName)
-        imported.add(defaultName)
-
-      const raw = namedPart.replace('}', '')
-      for (const segment of raw.split(',')) {
-        const cleaned = segment.trim().replace(TYPE_IMPORT_PREFIX_REGEX, '')
-        if (!cleaned)
-          continue
-        const [original] = cleaned.split(IMPORT_ALIAS_SPLIT_REGEX)
-        if (original)
-          imported.add(original.trim())
-      }
-      return
-    }
-
-    // namespace import: * as name
-    if (clause.startsWith('* as ')) {
-      const name = clause.replace('* as ', '').trim()
-      if (name)
-        imported.add(name)
-      return
-    }
-
-    // default import
-    imported.add(clause)
-  }
-
-  for (const line of lines) {
-    const trimmed = line.trim()
-    if (!buffer) {
-      if (!trimmed.startsWith('import '))
-        continue
-      buffer = trimmed
-      if (trimmed.endsWith(';')) {
-        flushImport(buffer)
-        buffer = ''
-      }
+  // 复用 Svelte 的 TS 解析器识别绑定，兼容无分号、跨行、注释及别名。
+  const ast = parse(`<script lang="ts">${scriptContent}</script>`, { modern: true })
+  for (const statement of ast.instance?.content.body ?? []) {
+    if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type')
       continue
-    }
-
-    buffer += ` ${trimmed}`
-    if (trimmed.endsWith(';')) {
-      flushImport(buffer)
-      buffer = ''
+    for (const specifier of statement.specifiers) {
+      if (specifier.importKind !== 'type')
+        imported.add(specifier.local.name)
     }
   }
-
-  if (buffer)
-    flushImport(buffer)
-
   return imported
 }
 

package/dist/components/compounds/Modal.svelte

@@ -28,6 +28,9 @@
   }: ModalProps & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
+  const modalId = $props.id()
+  const titleId = `${modalId}-title`
+  let panel = $state<HTMLDivElement>()
 
   // 标题区仅在显式提供标题或自定义 header 时出现；
   // 仅需关闭按钮的场景改为右上角悬浮按钮，避免业务侧额外占一整行头部。
@@ -91,16 +94,60 @@
     onclose?.()
   }
 
+  function focusableElements(): HTMLElement[] {
+    return [...(panel?.querySelectorAll<HTMLElement>('button, a[href], input:not([type="hidden"]), select, textarea, [tabindex]') ?? [])]
+      .filter(element => element.tabIndex >= 0 && !element.hasAttribute('disabled') && element.getClientRects().length > 0)
+  }
+
+  // 打开时把焦点移入弹窗，关闭后恢复原操作位置。
+  $effect(() => {
+    if (!open || !panel)
+      return
+    const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null
+    const elements = focusableElements()
+    const input = elements.find(element => element.matches('input:not([readonly]), textarea, select'))
+    const target = input ?? elements[0] ?? panel
+    target.focus()
+    return () => {
+      if (previous?.isConnected)
+        previous.focus()
+    }
+  })
+
+  function handleKeydown(event: KeyboardEvent) {
+    if (!open)
+      return
+    if (event.key === 'Escape' && closeOnEscape) {
+      event.preventDefault()
+      event.stopPropagation()
+      handleClose()
+    }
+    else if (event.key === 'Tab') {
+      const elements = focusableElements()
+      const first = elements[0]
+      const last = elements.at(-1)
+      if (!first) {
+        event.preventDefault()
+        panel?.focus()
+      }
+      else if (event.shiftKey && (document.activeElement === first || document.activeElement === panel)) {
+        event.preventDefault()
+        last?.focus()
+      }
+      else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault()
+        first.focus()
+      }
+    }
+  }
+
 </script>
 
 <div {...dataAttributes}
      class='hai-modal'
      style:display={open ? '' : 'none'}
      aria-hidden={open ? undefined : 'true'}
-     onkeydown={(e) => {
-       if (closeOnEscape && e.key === 'Escape')
-         handleClose()
-     }}
+     onkeydown={handleKeydown}
 >
   <div
     class='hai-modal__viewport'
@@ -117,7 +164,7 @@
       <div class='hai-modal__backdrop' aria-hidden='true'></div>
     {/if}
 
-    <div class={modalBoxClass} style={panelStyle}>
+    <div bind:this={panel} class={modalBoxClass} style={panelStyle} role='dialog' aria-modal='true' aria-labelledby={title && !header ? titleId : undefined} aria-label={title && !header ? undefined : title || uiM('common_dialog')} tabindex='-1'>
       {#if hasFloatingClose}
         <button
           type='button'
@@ -145,7 +192,7 @@
               {@render header()}
             </div>
           {:else if title}
-            <h3 class='flex-1 font-semibold text-[1.05rem] tracking-tight text-base-content/92'>
+            <h3 id={titleId} class='flex-1 font-semibold text-[1.05rem] tracking-tight text-base-content/92'>
               {title}
             </h3>
           {:else}

package/dist/components/primitives/BareInput.svelte

@@ -48,7 +48,9 @@
 
   const dataAttributes = $derived(getDataAttributes(restProps))
   function handleInput(e: Event & { currentTarget: HTMLInputElement }) {
-    value = e.currentTarget.value
+    // 文件输入的 value 由浏览器管理，不能把 fakepath 写回原生控件。
+    if (type !== 'file')
+      value = e.currentTarget.value
     oninput?.(e)
   }
 
@@ -94,7 +96,7 @@
        aria-controls={ariaControls}
        aria-autocomplete={ariaAutocomplete}
        class={className}
-       bind:value
+       value={type === 'file' ? undefined : value}
        oninput={handleInput}
        onchange={handleChange}
        onkeydown={handleKeydown}

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

@@ -10,7 +10,7 @@
   ```svelte
   <script>
     import { LanguageSwitch, createLocaleStore, setGlobalLocale } from '@h-ai/ui'
-    import { setLocale, getLocale } from '../../../paraglide/runtime.js'
+    import { setLocale, getLocale } from '$lib/paraglide/runtime.js'
 
     const localeStore = createLocaleStore()
   </script>

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

@@ -31,7 +31,7 @@ type $$ComponentProps = Props & DataAttributes;
  * ```svelte
  * <script>
  *   import { LanguageSwitch, createLocaleStore, setGlobalLocale } from '@h-ai/ui'
- *   import { setLocale, getLocale } from '../../../paraglide/runtime.js'
+ *   import { setLocale, getLocale } from '$lib/paraglide/runtime.js'
  *
  *   const localeStore = createLocaleStore()
  * </script>

package/dist/components/scenes/iam/UserProfile.svelte

@@ -26,6 +26,8 @@
     alwaysEditable = false,
     loading = false,
     fields = ['avatar', 'username', 'email', 'displayName', 'phone'],
+    avatarAccept = 'image/*',
+    avatarHint,
     class: className = '',
     errors = {},
     onsubmit,
@@ -34,6 +36,7 @@
   }: UserProfileProps & DataAttributes = $props()
 
   const dataAttributes = $derived(getDataAttributes(restProps))
+  const avatarInputId = $props.id()
   let editMode = $state(false)
   let formData = $state<UserProfileSubmitData>({
     username: '',
@@ -163,24 +166,25 @@
             <Avatar
               src={user?.avatarUrl ?? user?.avatar}
               alt={uiM('user_profile_avatar')}
+              name={user?.displayName || user?.nickname || user?.username}
               size='lg'
-              ring
               class='shadow-sm'
-              placeholder={user?.username?.charAt(0).toUpperCase() || 'U'}
             />
             {#if editable && (editMode || alwaysEditable)}
               <div>
                 <BareInput
+                  id={avatarInputId}
                   type='file'
-                  class='file-input file-input-sm w-full max-w-xs'
-                  accept='image/*'
+                  class='hidden'
+                  accept={avatarAccept}
                   disabled={loading}
                   onchange={handleAvatarChange}
                 />
+                <Button type='button' variant='outline' size='sm' disabled={loading} onclick={() => document.getElementById(avatarInputId)?.click()}>{uiM('user_profile_upload_avatar')}</Button>
                 {#if errors.avatar}
                   <p class='text-xs text-error mt-1' role='alert'>{errors.avatar}</p>
                 {:else}
-                  <p class='text-xs text-base-content/60 mt-1'>{uiM('user_profile_avatar_hint')}</p>
+                  <p class='text-xs text-base-content/60 mt-1'>{avatarHint ?? uiM('user_profile_avatar_hint')}</p>
                 {/if}
               </div>
             {/if}

package/dist/components/scenes/types.d.ts

@@ -299,6 +299,10 @@ export interface UserProfileProps extends DataAttributes {
     fields?: UserProfileField[];
     /** 头像上传地址 */
     avatarUploadUrl?: string;
+    /** 文件选择器允许的头像类型；最终校验由业务上传服务负责。 */
+    avatarAccept?: string;
+    /** 与业务上传限制一致的提示文案。 */
+    avatarHint?: string;
     /** 自定义类名 */
     class?: string;
     /** 错误信息 */

package/dist/messages/en-US.json

@@ -35,6 +35,7 @@
   "empty_title": "No data",
   "tag_input_placeholder": "Press Enter to add",
   "common_close": "Close",
+  "common_dialog": "Dialog",
   "modal_close": "Close modal",
   "drawer_close": "Close sidebar",
   "drawer_resize": "Resize drawer",
@@ -81,6 +82,7 @@
   "avatar_upload_invalid_type": "Please select an image file",
   "avatar_upload_failed": "Upload failed",
   "user_profile_avatar": "Avatar",
+  "user_profile_upload_avatar": "Upload avatar",
   "user_profile_username": "Username",
   "user_profile_email": "Email",
   "user_profile_display_name": "Display Name",

package/dist/messages/zh-CN.json

@@ -35,6 +35,7 @@
   "empty_title": "暂无数据",
   "tag_input_placeholder": "按 Enter 添加",
   "common_close": "关闭",
+  "common_dialog": "对话框",
   "modal_close": "关闭模态框",
   "drawer_close": "关闭侧边栏",
   "drawer_resize": "调整抽屉宽度",
@@ -81,6 +82,7 @@
   "avatar_upload_invalid_type": "请选择图片文件",
   "avatar_upload_failed": "上传失败",
   "user_profile_avatar": "头像",
+  "user_profile_upload_avatar": "上传头像",
   "user_profile_username": "用户名",
   "user_profile_email": "邮箱",
   "user_profile_display_name": "显示名称",

package/dist/theme-config.d.ts

@@ -154,9 +154,11 @@ export declare function applyTheme(theme: string, persist?: boolean): void;
  */
 export declare function getCurrentTheme(): string;
 /**
- * 获取保存的主题（从 localStorage）
+ * 获取保存的主题；存储为空或不可用时使用宿主默认主题。
+ *
+ * @param fallbackTheme - 未保存主题时的默认值，默认 light
  */
-export declare function getSavedTheme(): string;
+export declare function getSavedTheme(fallbackTheme?: string): string;
 /**
  * DaisyUI 主题配置字符串（用于 app.css）
  *

package/dist/theme-config.js

@@ -185,10 +185,12 @@ export function getCurrentTheme() {
     return document.documentElement.getAttribute('data-theme') ?? DEFAULT_THEME;
 }
 /**
- * 获取保存的主题（从 localStorage）
+ * 获取保存的主题；存储为空或不可用时使用宿主默认主题。
+ *
+ * @param fallbackTheme - 未保存主题时的默认值，默认 light
  */
-export function getSavedTheme() {
-    return readStoredValue(THEME_STORAGE_KEY) ?? DEFAULT_THEME;
+export function getSavedTheme(fallbackTheme = DEFAULT_THEME) {
+    return readStoredValue(THEME_STORAGE_KEY) ?? fallbackTheme;
 }
 /**
  * DaisyUI 主题配置字符串（用于 app.css）

package/dist/types.d.ts

@@ -160,7 +160,7 @@ export interface InputProps extends DataAttributes {
  * 无样式输入框属性
  */
 export interface BareInputProps extends DataAttributes {
-    /** 值 */
+    /** 文本值；file 类型通过事件读取 files，不绑定文件路径。 */
     value?: string;
     /** 占位符 */
     placeholder?: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.57",
+  "version": "0.1.0-alpha.58",
   "description": "Hai Framework UI component library for Svelte 5 Runes.",
   "license": "Apache-2.0",
   "svelte": "./dist/index.js",
@@ -19,6 +19,10 @@
       "types": "./vite.d.ts",
       "import": "./vite.js"
     },
+    "./theme": {
+      "types": "./dist/theme-config.d.ts",
+      "import": "./dist/theme-config.js"
+    },
     "./components/*": {
       "types": "./dist/components/*.d.ts",
       "svelte": "./dist/components/*.js",
@@ -39,35 +43,35 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
   },
   "peerDependencies": {
-    "svelte": "^5.55.9"
+    "svelte": "^5.57.2"
   },
   "dependencies": {
-    "@internationalized/date": "^3.8.0",
-    "@shikijs/langs": "^4.0.2",
-    "bits-ui": "^2.18.1",
+    "@h-ai/core": "0.1.0-alpha.58",
+    "@internationalized/date": "^3.12.4",
+    "@shikijs/langs": "^4.5.0",
+    "bits-ui": "^2.19.5",
     "html2canvas": "^1.4.1",
     "jspdf": "^4.2.1",
-    "layerchart": "2.0.1",
-    "marked": "^18.0.0",
-    "mermaid": "^11.12.0",
-    "shiki": "^4.0.2",
-    "tailwind-merge": "^3.5.0",
-    "@h-ai/core": "0.1.0-alpha.57"
+    "layerchart": "2.6.1",
+    "marked": "^18.1.0",
+    "mermaid": "^12.1.0",
+    "shiki": "^4.5.0",
+    "tailwind-merge": "^3.7.0"
   },
   "devDependencies": {
-    "@sveltejs/package": "^2.5.7",
-    "@sveltejs/vite-plugin-svelte": "^7.1.2",
-    "@types/node": "^25.9.1",
-    "jsdom": "^29.0.2",
+    "@sveltejs/package": "^3.0.0",
+    "@sveltejs/vite-plugin-svelte": "^7.3.1",
+    "@types/node": "^26.6.5",
+    "jsdom": "^30.1.2",
     "rimraf": "^6.1.3",
-    "svelte": "^5.55.9",
-    "svelte-check": "^4.4.8",
+    "svelte": "^5.57.2",
+    "svelte-check": "^4.7.6",
     "typescript": "^6.0.3",
-    "vite": "^8.0.14",
-    "vitest": "^4.1.7"
+    "vite": "^8.3.4",
+    "vitest": "^4.1.11"
   },
   "scripts": {
     "build": "svelte-package -i src/lib",
@@ -75,7 +79,7 @@
     "check": "svelte-check --tsconfig ./tsconfig.json",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "node ../../scripts/typecheck.mjs --noEmit",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "clean": "rimraf dist .turbo"