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

package/dist/components/scenes/iam/password-utils.d.ts

@@ -9,11 +9,49 @@
  * - 使用 NFKC 统一兼容字符
  */
 import type { PasswordPolicy } from '../types.js';
+/**
+ * 按约定进行 Unicode 归一化，保留用户密码的空白字符。
+ * @param value - 待处理或校验的值。
+ * @returns 按约定 Unicode 形式归一化的密码，保留空白字符。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const normalized = normalizePassword('Ａbcd1234!')
+ * ```
+ */
 export declare function normalizePassword(value: string): string;
 /**
  * 比较两次密码是否一致
+ * @param password - 用户输入的密码，不能持久化为 UI 偏好。
+ * @param confirmPassword - 再次输入的确认密码。
+ * @returns 归一化后两次密码输入是否一致。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const same = arePasswordsEqual('Ａbcd1234!', 'Abcd1234!')
+ * ```
  */
 export declare function arePasswordsEqual(password: string, confirmPassword: string): boolean;
-/** 与 IAM 密码策略一致的前端提示；服务端仍执行最终校验。 */
+/**
+ * 与 IAM 密码策略一致的前端提示；服务端仍执行最终校验。
+ * @param password - 用户输入的密码，不能持久化为 UI 偏好。
+ * @param policy - 服务端公开的密码策略。
+ * @returns 第一项未满足策略的提示，全部满足时为空字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const message = passwordPolicyError('Example-pass-42!', { minLength: 12, maxLength: 128, requireUppercase: true, requireLowercase: true, requireNumber: true, requireSpecialChar: true })
+ * ```
+ */
 export declare function passwordPolicyError(password: string, policy: PasswordPolicy): string;
+/**
+ * 按当前 UI 语言说明服务端公开的密码策略。
+ * @param policy - 服务端公开的密码策略。
+ * @returns 按当前 UI 语言拼接的密码策略说明。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const hint = passwordPolicyHint({ minLength: 12, maxLength: 128, requireUppercase: true, requireLowercase: true, requireNumber: true, requireSpecialChar: true })
+ * ```
+ */
 export declare function passwordPolicyHint(policy: PasswordPolicy): string;

package/dist/components/scenes/iam/password-utils.js

@@ -5,16 +5,44 @@
  * @module password-utils
  */
 import { uiM } from '../../../messages.js';
+/**
+ * 按约定进行 Unicode 归一化，保留用户密码的空白字符。
+ * @param value - 待处理或校验的值。
+ * @returns 按约定 Unicode 形式归一化的密码，保留空白字符。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const normalized = normalizePassword('Ａbcd1234!')
+ * ```
+ */
 export function normalizePassword(value) {
     return value.normalize('NFKC');
 }
 /**
  * 比较两次密码是否一致
+ * @param password - 用户输入的密码，不能持久化为 UI 偏好。
+ * @param confirmPassword - 再次输入的确认密码。
+ * @returns 归一化后两次密码输入是否一致。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const same = arePasswordsEqual('Ａbcd1234!', 'Abcd1234!')
+ * ```
  */
 export function arePasswordsEqual(password, confirmPassword) {
     return normalizePassword(password) === normalizePassword(confirmPassword);
 }
-/** 与 IAM 密码策略一致的前端提示；服务端仍执行最终校验。 */
+/**
+ * 与 IAM 密码策略一致的前端提示；服务端仍执行最终校验。
+ * @param password - 用户输入的密码，不能持久化为 UI 偏好。
+ * @param policy - 服务端公开的密码策略。
+ * @returns 第一项未满足策略的提示，全部满足时为空字符串。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const message = passwordPolicyError('Example-pass-42!', { minLength: 12, maxLength: 128, requireUppercase: true, requireLowercase: true, requireNumber: true, requireSpecialChar: true })
+ * ```
+ */
 export function passwordPolicyError(password, policy) {
     if (password.length < policy.minLength || password.length > policy.maxLength)
         return uiM('password_policy_length', { min: policy.minLength, max: policy.maxLength });
@@ -28,6 +56,16 @@ export function passwordPolicyError(password, policy) {
         return uiM('password_policy_special');
     return '';
 }
+/**
+ * 按当前 UI 语言说明服务端公开的密码策略。
+ * @param policy - 服务端公开的密码策略。
+ * @returns 按当前 UI 语言拼接的密码策略说明。
+ *
+ * @example 模块内部上下文
+ * ```ts
+ * const hint = passwordPolicyHint({ minLength: 12, maxLength: 128, requireUppercase: true, requireLowercase: true, requireNumber: true, requireSpecialChar: true })
+ * ```
+ */
 export function passwordPolicyHint(policy) {
     const requirements = [uiM('password_policy_length', { min: policy.minLength, max: policy.maxLength })];
     if (policy.requireUppercase)

package/dist/components/scenes/iam/permission-context.svelte.d.ts

@@ -6,20 +6,12 @@
  *
  * @example
  * ```svelte
- * <!-- +layout.svelte -->
- * <script>
- *   import { setPermissionContext } from '@h-ai/ui'
- *   setPermissionContext(() => data.user?.permissions ?? [])
- * </script>
- *
- * <!-- 子组件 -->
- * <script>
- *   import { usePermission } from '@h-ai/ui'
- *   const { hasPerm, hasAnyPerm, hasAllPerms } = usePermission()
+ * <script lang="ts">
+ *   import { setPermissionContext, PermGuard } from '@h-ai/ui'
+ *   const permissions = ['user:create']
+ *   setPermissionContext(() => permissions)
  * </script>
- * {#if hasPerm('user:create')}
- *   <button>新建用户</button>
- * {/if}
+ * <PermGuard permission="user:create"><button type="button">新建用户</button></PermGuard>
  * ```
  *
  * @module permission-context.svelte
@@ -35,9 +27,28 @@
  * @param required - 需要检查的权限码
  * @param userPermissions - 用户拥有的权限列表
  * @returns 是否匹配
+ *
+ * @example
+ * ```ts
+ * import { matchPermission } from '@h-ai/ui'
+ * const canRead = matchPermission('user:read', ['user:*'])
+ * const canDelete = matchPermission('user:delete', ['user:read'])
+ * ```
  */
 export declare function matchPermission(required: string, userPermissions: string[]): boolean;
-/** 权限上下文消费接口 */
+/**
+ * 权限上下文消费接口
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { usePermission } from '@h-ai/ui'
+ *   import type { PermissionContext } from '@h-ai/ui'
+ *   const permission: PermissionContext = usePermission()
+ * </script>
+ * {#if permission.hasPerm('user:read')}<span>用户列表</span>{/if}
+ * ```
+ */
 export interface PermissionContext {
     /** 当前用户权限列表（响应式） */
     readonly permissions: string[];
@@ -56,15 +67,16 @@ export interface PermissionContext {
  * 以便权限变化时自动触发子组件更新。
  *
  * @param getPermissions - 返回当前用户权限列表的函数
+ * @returns {void} 无返回值；注册当前组件树的权限读取函数。
  *
  * @example
  * ```svelte
- * <script>
+ * <script lang="ts">
  *   import { setPermissionContext } from '@h-ai/ui'
- *   let { data } = $props()
- *   const userPermissions = $derived(data.user?.permissions ?? [])
- *   setPermissionContext(() => userPermissions)
+ *   let permissions = $state(['user:read'])
+ *   setPermissionContext(() => permissions)
  * </script>
+ * <main>在此渲染需要权限上下文的子组件。</main>
  * ```
  */
 export declare function setPermissionContext(getPermissions: () => string[]): void;
@@ -78,13 +90,11 @@ export declare function setPermissionContext(getPermissions: () => string[]): vo
  *
  * @example
  * ```svelte
- * <script>
+ * <script lang="ts">
  *   import { usePermission } from '@h-ai/ui'
- *   const { hasPerm } = usePermission()
+ *   const permission = usePermission()
  * </script>
- * {#if hasPerm('role:create')}
- *   <button>创建角色</button>
- * {/if}
+ * {#if permission.hasAnyPerm('user:read', 'user:update')}<span>用户管理</span>{/if}
  * ```
  */
 export declare function usePermission(): PermissionContext;

package/dist/components/scenes/iam/permission-context.svelte.js

@@ -6,20 +6,12 @@
  *
  * @example
  * ```svelte
- * <!-- +layout.svelte -->
- * <script>
- *   import { setPermissionContext } from '@h-ai/ui'
- *   setPermissionContext(() => data.user?.permissions ?? [])
- * </script>
- *
- * <!-- 子组件 -->
- * <script>
- *   import { usePermission } from '@h-ai/ui'
- *   const { hasPerm, hasAnyPerm, hasAllPerms } = usePermission()
+ * <script lang="ts">
+ *   import { setPermissionContext, PermGuard } from '@h-ai/ui'
+ *   const permissions = ['user:create']
+ *   setPermissionContext(() => permissions)
  * </script>
- * {#if hasPerm('user:create')}
- *   <button>新建用户</button>
- * {/if}
+ * <PermGuard permission="user:create"><button type="button">新建用户</button></PermGuard>
  * ```
  *
  * @module permission-context.svelte
@@ -39,6 +31,13 @@ const PERMISSION_CONTEXT_KEY = Symbol('hai-permission-context');
  * @param required - 需要检查的权限码
  * @param userPermissions - 用户拥有的权限列表
  * @returns 是否匹配
+ *
+ * @example
+ * ```ts
+ * import { matchPermission } from '@h-ai/ui'
+ * const canRead = matchPermission('user:read', ['user:*'])
+ * const canDelete = matchPermission('user:delete', ['user:read'])
+ * ```
  */
 export function matchPermission(required, userPermissions) {
     for (const userPerm of userPermissions) {
@@ -58,15 +57,16 @@ export function matchPermission(required, userPermissions) {
  * 以便权限变化时自动触发子组件更新。
  *
  * @param getPermissions - 返回当前用户权限列表的函数
+ * @returns {void} 无返回值；注册当前组件树的权限读取函数。
  *
  * @example
  * ```svelte
- * <script>
+ * <script lang="ts">
  *   import { setPermissionContext } from '@h-ai/ui'
- *   let { data } = $props()
- *   const userPermissions = $derived(data.user?.permissions ?? [])
- *   setPermissionContext(() => userPermissions)
+ *   let permissions = $state(['user:read'])
+ *   setPermissionContext(() => permissions)
  * </script>
+ * <main>在此渲染需要权限上下文的子组件。</main>
  * ```
  */
 export function setPermissionContext(getPermissions) {
@@ -82,13 +82,11 @@ export function setPermissionContext(getPermissions) {
  *
  * @example
  * ```svelte
- * <script>
+ * <script lang="ts">
  *   import { usePermission } from '@h-ai/ui'
- *   const { hasPerm } = usePermission()
+ *   const permission = usePermission()
  * </script>
- * {#if hasPerm('role:create')}
- *   <button>创建角色</button>
- * {/if}
+ * {#if permission.hasAnyPerm('user:read', 'user:update')}<span>用户管理</span>{/if}
  * ```
  */
 export function usePermission() {

package/dist/components/scenes/storage/AvatarUpload.svelte

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

package/dist/components/scenes/storage/AvatarUpload.svelte.d.ts

@@ -1,6 +1,26 @@
 import type { DataAttributes } from '../../../types.js';
 import type { AvatarUploadProps } from '../types.js';
 type $$ComponentProps = AvatarUploadProps & DataAttributes;
+/**
+ * AvatarUpload
+ * =============================================================================
+ * @h-ai/ui - AvatarUpload 组件
+ * =============================================================================
+ * 头像上传组件（圆形）
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $derived)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { AvatarUpload } from '@h-ai/ui'
+ * const props: ComponentProps<typeof AvatarUpload> = { fallback: 'A', size: 'lg' }
+ * const component = mount(AvatarUpload, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const AvatarUpload: import("svelte").Component<$$ComponentProps, {}, "value">;
 type AvatarUpload = ReturnType<typeof AvatarUpload>;
 export default AvatarUpload;

package/dist/components/scenes/storage/FileList.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component FileList
   =============================================================================
   @h-ai/ui - FileList 组件
   =============================================================================
@@ -6,11 +7,21 @@
 
   使用 Svelte 5 Runes ($props, $state, $derived)
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { FileList } from '@h-ai/ui'
+  const props: ComponentProps<typeof FileList> = { files: [{ id: 'f1', name: 'report.pdf', size: 1024, type: 'application/pdf' }], showSize: true }
+  const component = mount(FileList, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
   import type { FileItem, FileListProps } from '../types.js'
-  import { uiM } from '../../../messages.js'
+  import { getUILocale, uiM } from '../../../messages.js'
   import { cn, getDataAttributes } from '../../../utils.js'
   import Button from '../../primitives/Button.svelte'
   import IconButton from '../../primitives/IconButton.svelte'
@@ -56,7 +67,7 @@
   // 格式化日期
   function formatDate(date: Date | string): string {
     const d = typeof date === 'string' ? new Date(date) : date
-    return d.toLocaleDateString('zh-CN', {
+    return d.toLocaleDateString(getUILocale(), {
       year: 'numeric',
       month: '2-digit',
       day: '2-digit',

package/dist/components/scenes/storage/FileList.svelte.d.ts

@@ -1,6 +1,26 @@
 import type { DataAttributes } from '../../../types.js';
 import type { FileListProps } from '../types.js';
 type $$ComponentProps = FileListProps & DataAttributes;
+/**
+ * FileList
+ * =============================================================================
+ * @h-ai/ui - FileList 组件
+ * =============================================================================
+ * 文件列表展示组件
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $derived)
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { FileList } from '@h-ai/ui'
+ * const props: ComponentProps<typeof FileList> = { files: [{ id: 'f1', name: 'report.pdf', size: 1024, type: 'application/pdf' }], showSize: true }
+ * const component = mount(FileList, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const FileList: import("svelte").Component<$$ComponentProps, {}, "">;
 type FileList = ReturnType<typeof FileList>;
 export default FileList;

package/dist/components/scenes/storage/FileUpload.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component FileUpload
   =============================================================================
   @h-ai/ui - FileUpload 组件
   =============================================================================
@@ -7,6 +8,16 @@
   使用 Svelte 5 Runes ($props, $state, $derived)
   使用 primitives 组件：Progress, IconButton
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { FileUpload } from '@h-ai/ui'
+  const props: ComponentProps<typeof FileUpload> = { accept: '.pdf', maxFiles: 3, autoUpload: false }
+  const component = mount(FileUpload, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'
@@ -287,12 +298,36 @@
     e.currentTarget.value = ''
   }
 
-  /** 手动触发上传 */
+  /**
+   * 手动触发上传
+   * @returns 当前待上传文件的上传 Promise；组件通过错误回调报告上传失败。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import { FileUpload } from '@h-ai/ui'
+   * const uploader = mount(FileUpload, { target: document.body, props: { autoUpload: false } })
+   * await uploader.upload()
+   * await unmount(uploader)
+   * ```
+   */
   export async function upload() {
     await uploadPendingFiles(files.filter(f => f.state === 'pending'))
   }
 
-  /** 清空文件列表 */
+  /**
+   * 清空文件列表
+   * @returns 无返回值；取消本组件请求并清空文件列表。
+   *
+   * @example
+   * ```ts
+   * import { mount, unmount } from 'svelte'
+   * import { FileUpload } from '@h-ai/ui'
+   * const uploader = mount(FileUpload, { target: document.body, props: { autoUpload: false } })
+   * uploader.clear()
+   * await unmount(uploader)
+   * ```
+   */
   export function clear() {
     abortAllActiveRequests()
     files = []

package/dist/components/scenes/storage/FileUpload.svelte.d.ts

@@ -1,6 +1,27 @@
 import type { DataAttributes } from '../../../types.js';
 import type { FileUploadProps } from '../types.js';
 type $$ComponentProps = FileUploadProps & DataAttributes;
+/**
+ * FileUpload
+ * =============================================================================
+ * @h-ai/ui - FileUpload 组件
+ * =============================================================================
+ * 文件上传组件，负责文件选择、校验、进度与列表展示
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $derived)
+ * 使用 primitives 组件：Progress, IconButton
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { FileUpload } from '@h-ai/ui'
+ * const props: ComponentProps<typeof FileUpload> = { accept: '.pdf', maxFiles: 3, autoUpload: false }
+ * const component = mount(FileUpload, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const FileUpload: import("svelte").Component<$$ComponentProps, {
     upload: () => Promise<void>;
     clear: () => void;

package/dist/components/scenes/storage/ImageUpload.svelte

@@ -1,4 +1,5 @@
 <!--
+  @component ImageUpload
   =============================================================================
   @h-ai/ui - ImageUpload 组件
   =============================================================================
@@ -7,6 +8,16 @@
   使用 Svelte 5 Runes ($props, $state, $derived)
   使用 primitives 组件：IconButton, Spinner
   =============================================================================
+
+  @example
+  ```ts
+  import { mount, unmount } from 'svelte'
+  import type { ComponentProps } from 'svelte'
+  import { ImageUpload } from '@h-ai/ui'
+  const props: ComponentProps<typeof ImageUpload> = { accept: 'image/png,image/jpeg', maxSize: 5 * 1024 * 1024 }
+  const component = mount(ImageUpload, { target: document.body, props })
+  await unmount(component)
+  ```
 -->
 <script lang='ts'>
   import type { DataAttributes } from '../../../types.js'

package/dist/components/scenes/storage/ImageUpload.svelte.d.ts

@@ -1,6 +1,27 @@
 import type { DataAttributes } from '../../../types.js';
 import type { ImageUploadProps } from '../types.js';
 type $$ComponentProps = ImageUploadProps & DataAttributes;
+/**
+ * ImageUpload
+ * =============================================================================
+ * @h-ai/ui - ImageUpload 组件
+ * =============================================================================
+ * 图片上传组件，支持预览
+ *
+ * 使用 Svelte 5 Runes ($props, $state, $derived)
+ * 使用 primitives 组件：IconButton, Spinner
+ * =============================================================================
+ *
+ * @example
+ * ```ts
+ * import { mount, unmount } from 'svelte'
+ * import type { ComponentProps } from 'svelte'
+ * import { ImageUpload } from '@h-ai/ui'
+ * const props: ComponentProps<typeof ImageUpload> = { accept: 'image/png,image/jpeg', maxSize: 5 * 1024 * 1024 }
+ * const component = mount(ImageUpload, { target: document.body, props })
+ * await unmount(component)
+ * ```
+ */
 declare const ImageUpload: import("svelte").Component<$$ComponentProps, {}, "value">;
 type ImageUpload = ReturnType<typeof ImageUpload>;
 export default ImageUpload;