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

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

@@ -1,4 +1,28 @@
-<!-- 配置驱动认证场景；网络、通知及 Token 存储由 actions 注入。 -->
+<!--
+  @component AuthPanel 配置驱动认证场景；网络、通知及 Token 存储由 actions 注入。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import { AuthPanel } from '@h-ai/ui'
+  import { apiClient } from '@h-ai/api-client'
+  import type { AuthPanelProps } from '@h-ai/ui'
+  const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1' })
+  if (!initialized.success) throw new Error(initialized.error.message)
+  try {
+    const result = await apiClient.iam.auth.publicConfig()
+    if (!result.success) throw new Error(result.error.message)
+    if (!result.data) throw new Error('Public auth configuration unavailable')
+    const actions = apiClient.createAuthActions(apiClient)
+    const props: AuthPanelProps = { config: result.data, actions, initialMode: 'login' }
+    const panel = mount(AuthPanel, { target: document.body, props })
+    await unmount(panel)
+  }
+  finally {
+    await apiClient.close()
+  }
+  ```
+-->
 <script lang='ts'>
   import type { HaiError, HaiResult } from '@h-ai/core'
   import type { UIMessageKey } from '../../../messages.js'
@@ -104,7 +128,7 @@
       {:else}
         {#if notice}<Alert variant='success' class='mb-4'>{uiM(notice)}</Alert>{/if}
         {#if mode === 'login'}
-          <LoginForm {columns} {labelPosition} {labelWidth} {methods} {loading} {errors} header={loginHeader} extraFields={loginFields} showRememberMe={false} showForgotPassword={config.passwordReset.enabled} {forgotPasswordUrl}
+          <LoginForm {columns} {labelPosition} {labelWidth} {methods} {loading} {errors} header={loginHeader} extraFields={loginFields} showForgotPassword={config.passwordReset.enabled} {forgotPasswordUrl}
                      onforgotpassword={forgotPasswordUrl ? undefined : () => switchMode('forgot')}
                      otpLength={config.otp.length} resendInterval={config.otp.resendInterval} onsendotp={actions.sendOtp}
                      agreements={config.agreements.showOnLogin ? config.agreements : undefined}

package/dist/components/scenes/iam/AuthPanel.svelte.d.ts

@@ -1,4 +1,29 @@
 import type { AuthPanelProps } from '../types.js';
+/**
+ * AuthPanel 配置驱动认证场景；网络、通知及 Token 存储由 actions 注入。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import { AuthPanel } from '@h-ai/ui'
+ * import { apiClient } from '@h-ai/api-client'
+ * import type { AuthPanelProps } from '@h-ai/ui'
+ * const initialized = await apiClient.init({ baseUrl: 'https://api.example.com/api/v1' })
+ * if (!initialized.success) throw new Error(initialized.error.message)
+ * try {
+ *   const result = await apiClient.iam.auth.publicConfig()
+ *   if (!result.success) throw new Error(result.error.message)
+ *   if (!result.data) throw new Error('Public auth configuration unavailable')
+ *   const actions = apiClient.createAuthActions(apiClient)
+ *   const props: AuthPanelProps = { config: result.data, actions, initialMode: 'login' }
+ *   const panel = mount(AuthPanel, { target: document.body, props })
+ *   await unmount(panel)
+ * }
+ * finally {
+ *   await apiClient.close()
+ * }
+ * ```
+ */
 declare const AuthPanel: import("svelte").Component<AuthPanelProps, {}, "">;
 type AuthPanel = ReturnType<typeof AuthPanel>;
 export default AuthPanel;

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

@@ -8,9 +8,14 @@
   使用 Svelte 5 Runes ($props, $derived)
 
   @example
-  <AuthShell variant="card" title="登录" subtitle="欢迎回来">
-    <LoginForm onsubmit={handleLogin} />
-  </AuthShell>
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { AuthShell } from '@h-ai/ui'
+  const props: ComponentProps<typeof AuthShell> = { variant: 'card', title: '登录', subtitle: '欢迎回来', children: createRawSnippet(() => ({ render: () => "<p>在此放置登录或注册表单。</p>" })) }
+  const component = mount(AuthShell, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'

package/dist/components/scenes/iam/AuthShell.svelte.d.ts

@@ -40,9 +40,14 @@ type $$ComponentProps = {
  * 使用 Svelte 5 Runes ($props, $derived)
  *
  * @example
- * <AuthShell variant="card" title="登录" subtitle="欢迎回来">
- *   <LoginForm onsubmit={handleLogin} />
- * </AuthShell>
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { AuthShell } from '@h-ai/ui'
+ * const props: ComponentProps<typeof AuthShell> = { variant: 'card', title: '登录', subtitle: '欢迎回来', children: createRawSnippet(() => ({ render: () => "<p>在此放置登录或注册表单。</p>" })) }
+ * const component = mount(AuthShell, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const AuthShell: import("svelte").Component<$$ComponentProps, {}, "">;
 type AuthShell = ReturnType<typeof AuthShell>;

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

@@ -1,6 +1,16 @@
 <!--
   @component ChangePasswordForm
   修改密码表单组件。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { ChangePasswordForm } from '@h-ai/ui'
+  const props: ComponentProps<typeof ChangePasswordForm> = { requireOldPassword: true, minPasswordLength: 12 }
+  const component = mount(ChangePasswordForm, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'

package/dist/components/scenes/iam/ChangePasswordForm.svelte.d.ts

@@ -4,6 +4,16 @@ type $$ComponentProps = ChangePasswordFormProps & DataAttributes;
 /**
  * ChangePasswordForm
  * 修改密码表单组件。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { ChangePasswordForm } from '@h-ai/ui'
+ * const props: ComponentProps<typeof ChangePasswordForm> = { requireOldPassword: true, minPasswordLength: 12 }
+ * const component = mount(ChangePasswordForm, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const ChangePasswordForm: import("svelte").Component<$$ComponentProps, {}, "">;
 type ChangePasswordForm = ReturnType<typeof ChangePasswordForm>;

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

@@ -1,4 +1,5 @@
 <!--
+  @component ForgotPasswordForm
   =============================================================================
   @h-ai/ui - ForgotPasswordForm 组件
   =============================================================================
@@ -7,6 +8,16 @@
   使用 Svelte 5 Runes ($props, $state, $derived)
   使用 primitives/compounds 组件：Input, Button, Alert
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { ForgotPasswordForm } from '@h-ai/ui'
+  const props: ComponentProps<typeof ForgotPasswordForm> = { mode: 'email' }
+  const component = mount(ForgotPasswordForm, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'

package/dist/components/scenes/iam/ForgotPasswordForm.svelte.d.ts

@@ -1,6 +1,27 @@
 import type { DataAttributes } from '../../../types.js';
 import type { ForgotPasswordFormProps } from '../types.js';
 type $$ComponentProps = ForgotPasswordFormProps & DataAttributes;
+/**
+ * ForgotPasswordForm
+ * =============================================================================
+ * @h-ai/ui - ForgotPasswordForm 组件
+ * =============================================================================
+ * 找回密码表单组件
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $derived)
+ * 使用 primitives/compounds 组件：Input, Button, Alert
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { ForgotPasswordForm } from '@h-ai/ui'
+ * const props: ComponentProps<typeof ForgotPasswordForm> = { mode: 'email' }
+ * const component = mount(ForgotPasswordForm, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const ForgotPasswordForm: import("svelte").Component<$$ComponentProps, {}, "">;
 type ForgotPasswordForm = ReturnType<typeof ForgotPasswordForm>;
 export default ForgotPasswordForm;

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

@@ -1,6 +1,16 @@
 <!--
   @component LoginForm
   用户登录表单组件，搭配 primitives/compounds 使用。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { LoginForm } from '@h-ai/ui'
+  const props: ComponentProps<typeof LoginForm> = { methods: ['password'] }
+  const component = mount(LoginForm, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { HaiError } from '@h-ai/core'
@@ -13,7 +23,6 @@
   import FormLayout from '../../compounds/FormLayout.svelte'
   import BareButton from '../../primitives/BareButton.svelte'
   import Button from '../../primitives/Button.svelte'
-  import Checkbox from '../../primitives/Checkbox.svelte'
   import Input from '../../primitives/Input.svelte'
   import AgreementNotice from './AgreementNotice.svelte'
   import { authErrorMessage } from './auth-error-message.js'
@@ -30,7 +39,6 @@
     labelWidth = '8rem',
     disabled = false,
     showTitle = false,
-    showRememberMe = true,
     showForgotPassword = true,
     forgotPasswordUrl = '/forgot-password',
     showRegisterLink = false,
@@ -51,7 +59,6 @@
 
   let username = $state('')
   let password = $state('')
-  let rememberMe = $state(false)
   let selectedMethod = $state<AuthLoginMethod>('password')
   const method = $derived(methods.includes(selectedMethod) ? selectedMethod : methods[0])
   const isOtp = $derived(method === 'email' || method === 'sms')
@@ -118,7 +125,6 @@
     const data: LoginFormData = {
       username,
       password,
-      rememberMe,
       method,
       code: isOtp ? code : undefined,
     }
@@ -204,34 +210,21 @@
       {/if}
     {/if}
 
-    <!-- 记住我 & 忘记密码 -->
-    {#if method === 'password' && (showRememberMe || showForgotPassword)}
-      <div class='flex items-center justify-between'>
-        {#if showRememberMe}
-          <Checkbox
-            bind:checked={rememberMe}
-            label={uiM('login_remember_me')}
-            {disabled}
-            size='sm'
-          />
+    <!-- 忘记密码 -->
+    {#if method === 'password' && showForgotPassword}
+      <div class='flex justify-end'>
+        {#if onforgotpassword}
+          <BareButton
+            type='button'
+            class='link link-primary text-sm'
+            onclick={handleForgotPassword}
+          >
+            {uiM('login_forgot_password')}
+          </BareButton>
         {:else}
-          <div></div>
-        {/if}
-
-        {#if showForgotPassword}
-          {#if onforgotpassword}
-            <BareButton
-              type='button'
-              class='link link-primary text-sm'
-              onclick={handleForgotPassword}
-            >
-              {uiM('login_forgot_password')}
-            </BareButton>
-          {:else}
-            <a href={forgotPasswordUrl} class='link link-primary text-sm'>
-              {uiM('login_forgot_password')}
-            </a>
-          {/if}
+          <a href={forgotPasswordUrl} class='link link-primary text-sm'>
+            {uiM('login_forgot_password')}
+          </a>
         {/if}
       </div>
     {/if}

package/dist/components/scenes/iam/LoginForm.svelte.d.ts

@@ -4,6 +4,16 @@ type $$ComponentProps = LoginFormProps & DataAttributes;
 /**
  * LoginForm
  * 用户登录表单组件，搭配 primitives/compounds 使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { LoginForm } from '@h-ai/ui'
+ * const props: ComponentProps<typeof LoginForm> = { methods: ['password'] }
+ * const component = mount(LoginForm, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const LoginForm: import("svelte").Component<$$ComponentProps, {}, "">;
 type LoginForm = ReturnType<typeof LoginForm>;

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

@@ -2,6 +2,16 @@
   @component PasswordInput
   密码输入框组件，支持显示/隐藏切换和密码强度指示。
   内置多语言支持，自动跟随全局 locale。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { PasswordInput } from '@h-ai/ui'
+  const props: ComponentProps<typeof PasswordInput> = { value: '', autocomplete: 'new-password', showStrength: true, minLength: 12 }
+  const component = mount(PasswordInput, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, FormText, Size } from '../../../types.js'
@@ -19,6 +29,19 @@
   const PASSWORD_DIGIT_REGEX = /\d/
   const PASSWORD_SPECIAL_CHAR_REGEX = /[^a-z0-9]/i
 
+  /**
+   * PasswordInput 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { PasswordInput } from '@h-ai/ui'
+   * const props: ComponentProps<typeof PasswordInput> = { value: '', autocomplete: 'new-password', showStrength: true, minLength: 12 }
+   * const component = mount(PasswordInput, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 元素 ID */
     id?: string

package/dist/components/scenes/iam/PasswordInput.svelte.d.ts

@@ -1,4 +1,17 @@
 import type { DataAttributes, FormText, Size } from '../../../types.js';
+/**
+ * PasswordInput 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { PasswordInput } from '@h-ai/ui'
+ * const props: ComponentProps<typeof PasswordInput> = { value: '', autocomplete: 'new-password', showStrength: true, minLength: 12 }
+ * const component = mount(PasswordInput, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 元素 ID */
     id?: string;
@@ -46,6 +59,16 @@ type $$ComponentProps = Props & DataAttributes;
  * PasswordInput
  * 密码输入框组件，支持显示/隐藏切换和密码强度指示。
  * 内置多语言支持，自动跟随全局 locale。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { PasswordInput } from '@h-ai/ui'
+ * const props: ComponentProps<typeof PasswordInput> = { value: '', autocomplete: 'new-password', showStrength: true, minLength: 12 }
+ * const component = mount(PasswordInput, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const PasswordInput: import("svelte").Component<$$ComponentProps, {}, "value" | "inputRef">;
 type PasswordInput = ReturnType<typeof PasswordInput>;

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

@@ -1,27 +1,37 @@
 <!--
+  @component PermGuard
   @h-ai/ui — PermGuard 权限守卫组件
 
   根据权限上下文条件渲染子内容。
   当用户拥有指定权限时渲染 children，否则渲染 fallback（可选）。
 
   @example
-  ```svelte
-  <PermGuard permission="user:create">
-    <button>新建用户</button>
-  </PermGuard>
-
-  <PermGuard permissions={['user:update', 'user:delete']} mode="any">
-    <button>操作</button>
-    {#snippet fallback()}
-      <span>无权限</span>
-    {/snippet}
-  </PermGuard>
+  ```ts
+  import { mount, unmount, createRawSnippet } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { PermGuard } from '@h-ai/ui'
+  const props: ComponentProps<typeof PermGuard> = { permission: 'user:read', children: createRawSnippet(() => ({ render: () => "<span>用户列表</span>" })) }
+  const component = mount(PermGuard, { target: document.body, props })
+  await unmount(component)
   ```
 -->
 <script lang='ts'>
   import type { Snippet } from 'svelte'
   import { usePermission } from './permission-context.svelte.js'
 
+  /**
+   * PermGuard 组件的属性契约；通过公开组件配置使用。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount, createRawSnippet } from 'svelte'
+   * import type { ComponentProps } from 'svelte'
+   * import { PermGuard } from '@h-ai/ui'
+   * const props: ComponentProps<typeof PermGuard> = { permission: 'user:read', children: createRawSnippet(() => ({ render: () => "<span>用户列表</span>" })) }
+   * const component = mount(PermGuard, { target: document.body, props })
+   * await unmount(component)
+   * ```
+   */
   interface Props {
     /** 单个权限码 */
     permission?: string

package/dist/components/scenes/iam/PermGuard.svelte.d.ts

@@ -1,4 +1,17 @@
 import type { Snippet } from 'svelte';
+/**
+ * PermGuard 组件的属性契约；通过公开组件配置使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { PermGuard } from '@h-ai/ui'
+ * const props: ComponentProps<typeof PermGuard> = { permission: 'user:read', children: createRawSnippet(() => ({ render: () => "<span>用户列表</span>" })) }
+ * const component = mount(PermGuard, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 interface Props {
     /** 单个权限码 */
     permission?: string;
@@ -11,6 +24,23 @@ interface Props {
     /** 授权未通过时渲染的内容（可选） */
     fallback?: Snippet;
 }
+/**
+ * PermGuard
+ * @h-ai/ui — PermGuard 权限守卫组件
+ *
+ * 根据权限上下文条件渲染子内容。
+ * 当用户拥有指定权限时渲染 children，否则渲染 fallback（可选）。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount, createRawSnippet } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { PermGuard } from '@h-ai/ui'
+ * const props: ComponentProps<typeof PermGuard> = { permission: 'user:read', children: createRawSnippet(() => ({ render: () => "<span>用户列表</span>" })) }
+ * const component = mount(PermGuard, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const PermGuard: import("svelte").Component<Props, {}, "">;
 type PermGuard = ReturnType<typeof PermGuard>;
 export default PermGuard;

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

@@ -1,6 +1,16 @@
 <!--
   @component RegisterForm
   用户注册表单组件，搭配 primitives/compounds 使用。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { RegisterForm } from '@h-ai/ui'
+  const props: ComponentProps<typeof RegisterForm> = { fields: ['username', 'password'], requireConfirmPassword: true }
+  const component = mount(RegisterForm, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes, InputProps } from '../../../types.js'

package/dist/components/scenes/iam/RegisterForm.svelte.d.ts

@@ -4,6 +4,16 @@ type $$ComponentProps = RegisterFormProps & DataAttributes;
 /**
  * RegisterForm
  * 用户注册表单组件，搭配 primitives/compounds 使用。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { RegisterForm } from '@h-ai/ui'
+ * const props: ComponentProps<typeof RegisterForm> = { fields: ['username', 'password'], requireConfirmPassword: true }
+ * const component = mount(RegisterForm, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const RegisterForm: import("svelte").Component<$$ComponentProps, {}, "">;
 type RegisterForm = ReturnType<typeof RegisterForm>;

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

@@ -1,6 +1,16 @@
 <!--
   @component ResetPasswordForm
   重置密码表单组件（配合验证码/链接使用）。
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { ResetPasswordForm } from '@h-ai/ui'
+  const props: ComponentProps<typeof ResetPasswordForm> = { showCode: true, minPasswordLength: 12 }
+  const component = mount(ResetPasswordForm, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'

package/dist/components/scenes/iam/ResetPasswordForm.svelte.d.ts

@@ -4,6 +4,16 @@ type $$ComponentProps = ResetPasswordFormProps & DataAttributes;
 /**
  * ResetPasswordForm
  * 重置密码表单组件（配合验证码/链接使用）。
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { ResetPasswordForm } from '@h-ai/ui'
+ * const props: ComponentProps<typeof ResetPasswordForm> = { showCode: true, minPasswordLength: 12 }
+ * const component = mount(ResetPasswordForm, { target: document.body, props })
+ * await unmount(component)
+ * ```
  */
 declare const ResetPasswordForm: import("svelte").Component<$$ComponentProps, {}, "">;
 type ResetPasswordForm = ReturnType<typeof ResetPasswordForm>;

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

@@ -1,4 +1,5 @@
 <!--
+  @component UserProfile
   =============================================================================
   @h-ai/ui - UserProfile 组件
   =============================================================================
@@ -7,6 +8,16 @@
   使用 Svelte 5 Runes ($props, $state, $derived)
   使用 primitives/compounds 组件：Input, Button, Textarea, Avatar, Alert
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { UserProfile } from '@h-ai/ui'
+  const props: ComponentProps<typeof UserProfile> = { user: { id: 'u1', username: 'ada', email: 'ada@example.com' }, fields: ['username', 'email'], editable: true }
+  const component = mount(UserProfile, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'

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

@@ -1,6 +1,27 @@
 import type { DataAttributes } from '../../../types.js';
 import type { UserProfileProps } from '../types.js';
 type $$ComponentProps = UserProfileProps & DataAttributes;
+/**
+ * UserProfile
+ * =============================================================================
+ * @h-ai/ui - UserProfile 组件
+ * =============================================================================
+ * 用户个人信息展示/编辑组件
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $derived)
+ * 使用 primitives/compounds 组件：Input, Button, Textarea, Avatar, Alert
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { UserProfile } from '@h-ai/ui'
+ * const props: ComponentProps<typeof UserProfile> = { user: { id: 'u1', username: 'ada', email: 'ada@example.com' }, fields: ['username', 'email'], editable: true }
+ * const component = mount(UserProfile, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const UserProfile: import("svelte").Component<$$ComponentProps, {}, "">;
 type UserProfile = ReturnType<typeof UserProfile>;
 export default UserProfile;

package/dist/components/scenes/iam/auth-error-message.d.ts

@@ -1,2 +1,12 @@
 import type { HaiError } from '@h-ai/core';
+/**
+ * 将已知 IAM 错误码映射为当前语言的认证提示，未知错误保留原消息。
+ * @param error - 待显示的安全错误对象或消息。
+ * @returns 当前语言的已知认证错误提示；未知错误保留服务端消息。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const message = authErrorMessage({ code: 'hai:iam:020', message: '登录失败' })
+ * ```
+ */
 export declare function authErrorMessage(error: Pick<HaiError, 'code' | 'message'>): string;

package/dist/components/scenes/iam/auth-error-message.js

@@ -27,6 +27,16 @@ const messages = {
     'hai:iam:901': 'auth_error_service',
     'hai:iam:999': 'auth_error_service',
 };
+/**
+ * 将已知 IAM 错误码映射为当前语言的认证提示，未知错误保留原消息。
+ * @param error - 待显示的安全错误对象或消息。
+ * @returns 当前语言的已知认证错误提示；未知错误保留服务端消息。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const message = authErrorMessage({ code: 'hai:iam:020', message: '登录失败' })
+ * ```
+ */
 export function authErrorMessage(error) {
     const key = messages[error.code];
     return key ? uiM(key) : error.message;