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

package/dist/utils/platform.svelte.d.ts

@@ -4,7 +4,15 @@
  * 提供运行时平台检测与 Svelte 5 响应式平台状态。
  * @module platform
  */
-/** 运行平台 */
+/**
+ * 运行平台
+ *
+ * @example
+ * ```ts
+ * import type { Platform } from '@h-ai/ui'
+ * const example: Platform = 'web'
+ * ```
+ */
 export type Platform = 'web' | 'h5' | 'android' | 'ios' | 'unknown';
 /**
  * 检测当前运行平台
@@ -13,19 +21,31 @@ export type Platform = 'web' | 'h5' | 'android' | 'ios' | 'unknown';
  *
  * @example
  * ```ts
+ * import { detectPlatform } from '@h-ai/ui'
  * const platform = detectPlatform()
- * if (platform === 'android') {
- *   // Android 特定逻辑
- * }
  * ```
  */
 export declare function detectPlatform(): Platform;
 /**
  * 判断是否为移动端
+ * @returns 当前是否为 H5 或 Android/iOS 原生壳。
+ *
+ * @example
+ * ```ts
+ * import { isMobile } from '@h-ai/ui'
+ * const compactLayout = isMobile()
+ * ```
  */
 export declare function isMobile(): boolean;
 /**
  * 判断是否为 Capacitor App
+ * @returns 是否为 Capacitor Android/iOS 原生壳。
+ *
+ * @example
+ * ```ts
+ * import { isNativeApp } from '@h-ai/ui'
+ * const useNativeBridge = isNativeApp()
+ * ```
  */
 export declare function isNativeApp(): boolean;
 /**
@@ -34,17 +54,10 @@ export declare function isNativeApp(): boolean;
  * @returns 包含当前平台、是否移动端和是否原生应用的响应式对象
  *
  * @example
- * ```svelte
- * <script>
- *   import { usePlatform } from '@hai/ui'
- *   const platform = usePlatform()
- * </script>
- *
- * {#if platform.isMobile}
- *   <BottomNav />
- * {:else}
- *   <Sidebar />
- * {/if}
+ * ```ts
+ * import { usePlatform } from '@h-ai/ui'
+ * const platform = usePlatform()
+ * const device = platform.current
  * ```
  */
 export declare function usePlatform(): {

package/dist/utils/platform.svelte.js

@@ -13,10 +13,8 @@ const IOS_UA_REGEX = /iphone|ipad|ipod/;
  *
  * @example
  * ```ts
+ * import { detectPlatform } from '@h-ai/ui'
  * const platform = detectPlatform()
- * if (platform === 'android') {
- *   // Android 特定逻辑
- * }
  * ```
  */
 export function detectPlatform() {
@@ -46,6 +44,13 @@ export function detectPlatform() {
 }
 /**
  * 判断是否为移动端
+ * @returns 当前是否为 H5 或 Android/iOS 原生壳。
+ *
+ * @example
+ * ```ts
+ * import { isMobile } from '@h-ai/ui'
+ * const compactLayout = isMobile()
+ * ```
  */
 export function isMobile() {
     const platform = detectPlatform();
@@ -53,6 +58,13 @@ export function isMobile() {
 }
 /**
  * 判断是否为 Capacitor App
+ * @returns 是否为 Capacitor Android/iOS 原生壳。
+ *
+ * @example
+ * ```ts
+ * import { isNativeApp } from '@h-ai/ui'
+ * const useNativeBridge = isNativeApp()
+ * ```
  */
 export function isNativeApp() {
     const platform = detectPlatform();
@@ -64,17 +76,10 @@ export function isNativeApp() {
  * @returns 包含当前平台、是否移动端和是否原生应用的响应式对象
  *
  * @example
- * ```svelte
- * <script>
- *   import { usePlatform } from '@hai/ui'
- *   const platform = usePlatform()
- * </script>
- *
- * {#if platform.isMobile}
- *   <BottomNav />
- * {:else}
- *   <Sidebar />
- * {/if}
+ * ```ts
+ * import { usePlatform } from '@h-ai/ui'
+ * const platform = usePlatform()
+ * const device = platform.current
  * ```
  */
 export function usePlatform() {

package/dist/utils.d.ts

@@ -10,43 +10,135 @@ import type { DataAttributes, Size, Variant } from './types.js';
  *
  * @param classes - 类名列表
  * @returns 合并后的类名字符串
+ *
+ * @example
+ * ```ts
+ * import { cn } from '@h-ai/ui'
+ * const classes = cn('px-2', 'px-4', false, 'font-medium')
+ * // classes 为冲突合并后的类名，可直接用于元素 class。
+ * ```
  */
 export declare function cn(...classes: (string | boolean | undefined | null)[]): string;
+/**
+ * 实际可转发的 data-* 原子值映射，不包含 null 或 undefined。
+ *
+ * @example
+ * ```ts
+ * import type { ForwardedDataAttributes } from '@h-ai/ui'
+ * const example: ForwardedDataAttributes = { 'data-testid': 'profile-save' }
+ * ```
+ */
 export type ForwardedDataAttributes = Record<`data-${string}`, string | number | boolean>;
 /**
  * 从组件未声明 props 中提取 data-* 属性，避免把普通未知属性透传到 DOM。
+ * @param props - 组件的属性对象。
+ * @returns 只包含安全原子值的 data-* 属性对象。
+ *
+ * @example
+ * ```ts
+ * import { getDataAttributes } from '@h-ai/ui'
+ * const attributes = getDataAttributes({ 'data-testid': 'save', 'data-loading': false, onclick: 'ignored' })
+ * // 仅保留安全类型的 data-* 字段。
+ * ```
  */
 export declare function getDataAttributes(props: DataAttributes | Record<string, unknown>): ForwardedDataAttributes;
 /**
  * 获取变体类名
+ * @param variant - 语义变体。
+ * @param prefix - 类名前缀或界面 ID 前缀。
+ * @returns 对应前缀和变体的 DaisyUI 类名；未知前缀按约定拼接。
+ *
+ * @example
+ * ```ts
+ * import { getVariantClass } from '@h-ai/ui'
+ * const classes = getVariantClass('primary', 'btn')
+ * ```
  */
 export declare function getVariantClass(variant: Variant, prefix?: string): string;
 /**
  * 获取尺寸类名
+ * @param size - 组件尺寸预设。
+ * @param prefix - 类名前缀或界面 ID 前缀。
+ * @returns 对应尺寸的类名，中号尺寸使用空字符串。
+ *
+ * @example
+ * ```ts
+ * import { getSizeClass } from '@h-ai/ui'
+ * const classes = getSizeClass('lg', 'btn')
+ * ```
  */
 export declare function getSizeClass(size: Size, prefix?: string): string;
 /**
  * 输入框尺寸类名
+ * @param size - 组件尺寸预设。
+ * @returns 输入框尺寸类名；大于 xl 的预设统一使用 input-xl。
+ *
+ * @example
+ * ```ts
+ * import { getInputSizeClass } from '@h-ai/ui'
+ * const classes = getInputSizeClass('sm')
+ * ```
  */
 export declare function getInputSizeClass(size: Size): string;
 /**
  * 徽章变体类名
+ * @param variant - 语义变体。
+ * @returns 徽章语义变体类名。
+ *
+ * @example
+ * ```ts
+ * import { getBadgeVariantClass } from '@h-ai/ui'
+ * const classes = getBadgeVariantClass('success')
+ * ```
  */
 export declare function getBadgeVariantClass(variant: Variant): string;
 /**
  * 徽章尺寸类名
+ * @param size - 组件尺寸预设。
+ * @returns 徽章尺寸类名。
+ *
+ * @example
+ * ```ts
+ * import { getBadgeSizeClass } from '@h-ai/ui'
+ * const classes = getBadgeSizeClass('sm')
+ * ```
  */
 export declare function getBadgeSizeClass(size: Size): string;
 /**
  * 警告框变体类名
+ * @param variant - 语义变体。
+ * @returns 警告框语义变体类名。
+ *
+ * @example
+ * ```ts
+ * import { getAlertVariantClass } from '@h-ai/ui'
+ * const classes = getAlertVariantClass('warning')
+ * ```
  */
 export declare function getAlertVariantClass(variant: Variant): string;
 /**
  * 进度条变体类名
+ * @param variant - 语义变体。
+ * @returns 进度条语义变体类名。
+ *
+ * @example
+ * ```ts
+ * import { getProgressVariantClass } from '@h-ai/ui'
+ * const classes = getProgressVariantClass('success')
+ * ```
  */
 export declare function getProgressVariantClass(variant: Variant): string;
 /**
  * 生成唯一 ID
+ * @param prefix - 类名前缀或界面 ID 前缀。
+ * @returns 用于界面节点关联的随机 ID，不具备安全令牌或分布式主键保证。
+ *
+ * @example
+ * ```ts
+ * import { generateId } from '@h-ai/ui'
+ * const inputId = generateId('profile-email')
+ * // 仅用于界面节点关联，不用作安全令牌或分布式业务主键。
+ * ```
  */
 export declare function generateId(prefix?: string): string;
 /**
@@ -57,6 +149,16 @@ export declare function generateId(prefix?: string): string;
  *
  * @param node - 要移动的节点
  * @param target - 目标容器或选择器；默认 body
+ * @returns 包含 update 和 destroy 的 Svelte action 句柄。
+ *
+ * @example
+ * ```ts
+ * import { portal } from '@h-ai/ui'
+ * const popup = document.createElement('div')
+ * const action = portal(popup, document.body)
+ * action.update(document.body)
+ * action.destroy()
+ * ```
  */
 export declare function portal(node: HTMLElement, target?: HTMLElement | string): {
     update(next: HTMLElement | string): void;

package/dist/utils.js

@@ -10,12 +10,28 @@ import { twMerge } from 'tailwind-merge';
  *
  * @param classes - 类名列表
  * @returns 合并后的类名字符串
+ *
+ * @example
+ * ```ts
+ * import { cn } from '@h-ai/ui'
+ * const classes = cn('px-2', 'px-4', false, 'font-medium')
+ * // classes 为冲突合并后的类名，可直接用于元素 class。
+ * ```
  */
 export function cn(...classes) {
     return twMerge(classes.filter(Boolean).join(' '));
 }
 /**
  * 从组件未声明 props 中提取 data-* 属性，避免把普通未知属性透传到 DOM。
+ * @param props - 组件的属性对象。
+ * @returns 只包含安全原子值的 data-* 属性对象。
+ *
+ * @example
+ * ```ts
+ * import { getDataAttributes } from '@h-ai/ui'
+ * const attributes = getDataAttributes({ 'data-testid': 'save', 'data-loading': false, onclick: 'ignored' })
+ * // 仅保留安全类型的 data-* 字段。
+ * ```
  */
 export function getDataAttributes(props) {
     const dataAttributes = {};
@@ -99,6 +115,15 @@ const SIZE_MAPS = {
 };
 /**
  * 获取变体类名
+ * @param variant - 语义变体。
+ * @param prefix - 类名前缀或界面 ID 前缀。
+ * @returns 对应前缀和变体的 DaisyUI 类名；未知前缀按约定拼接。
+ *
+ * @example
+ * ```ts
+ * import { getVariantClass } from '@h-ai/ui'
+ * const classes = getVariantClass('primary', 'btn')
+ * ```
  */
 export function getVariantClass(variant, prefix = 'btn') {
     const map = VARIANT_MAPS[prefix];
@@ -109,6 +134,15 @@ export function getVariantClass(variant, prefix = 'btn') {
 }
 /**
  * 获取尺寸类名
+ * @param size - 组件尺寸预设。
+ * @param prefix - 类名前缀或界面 ID 前缀。
+ * @returns 对应尺寸的类名，中号尺寸使用空字符串。
+ *
+ * @example
+ * ```ts
+ * import { getSizeClass } from '@h-ai/ui'
+ * const classes = getSizeClass('lg', 'btn')
+ * ```
  */
 export function getSizeClass(size, prefix = 'btn') {
     if (size === 'md')
@@ -120,6 +154,14 @@ export function getSizeClass(size, prefix = 'btn') {
 }
 /**
  * 输入框尺寸类名
+ * @param size - 组件尺寸预设。
+ * @returns 输入框尺寸类名；大于 xl 的预设统一使用 input-xl。
+ *
+ * @example
+ * ```ts
+ * import { getInputSizeClass } from '@h-ai/ui'
+ * const classes = getInputSizeClass('sm')
+ * ```
  */
 export function getInputSizeClass(size) {
     const map = {
@@ -136,18 +178,42 @@ export function getInputSizeClass(size) {
 }
 /**
  * 徽章变体类名
+ * @param variant - 语义变体。
+ * @returns 徽章语义变体类名。
+ *
+ * @example
+ * ```ts
+ * import { getBadgeVariantClass } from '@h-ai/ui'
+ * const classes = getBadgeVariantClass('success')
+ * ```
  */
 export function getBadgeVariantClass(variant) {
     return getVariantClass(variant, 'badge');
 }
 /**
  * 徽章尺寸类名
+ * @param size - 组件尺寸预设。
+ * @returns 徽章尺寸类名。
+ *
+ * @example
+ * ```ts
+ * import { getBadgeSizeClass } from '@h-ai/ui'
+ * const classes = getBadgeSizeClass('sm')
+ * ```
  */
 export function getBadgeSizeClass(size) {
     return getSizeClass(size, 'badge');
 }
 /**
  * 警告框变体类名
+ * @param variant - 语义变体。
+ * @returns 警告框语义变体类名。
+ *
+ * @example
+ * ```ts
+ * import { getAlertVariantClass } from '@h-ai/ui'
+ * const classes = getAlertVariantClass('warning')
+ * ```
  */
 export function getAlertVariantClass(variant) {
     const map = {
@@ -166,12 +232,29 @@ export function getAlertVariantClass(variant) {
 }
 /**
  * 进度条变体类名
+ * @param variant - 语义变体。
+ * @returns 进度条语义变体类名。
+ *
+ * @example
+ * ```ts
+ * import { getProgressVariantClass } from '@h-ai/ui'
+ * const classes = getProgressVariantClass('success')
+ * ```
  */
 export function getProgressVariantClass(variant) {
     return getVariantClass(variant, 'progress');
 }
 /**
  * 生成唯一 ID
+ * @param prefix - 类名前缀或界面 ID 前缀。
+ * @returns 用于界面节点关联的随机 ID，不具备安全令牌或分布式主键保证。
+ *
+ * @example
+ * ```ts
+ * import { generateId } from '@h-ai/ui'
+ * const inputId = generateId('profile-email')
+ * // 仅用于界面节点关联，不用作安全令牌或分布式业务主键。
+ * ```
  */
 export function generateId(prefix = 'hai') {
     return `${prefix}-${Math.random().toString(36).slice(2, 9)}`;
@@ -184,6 +267,16 @@ export function generateId(prefix = 'hai') {
  *
  * @param node - 要移动的节点
  * @param target - 目标容器或选择器；默认 body
+ * @returns 包含 update 和 destroy 的 Svelte action 句柄。
+ *
+ * @example
+ * ```ts
+ * import { portal } from '@h-ai/ui'
+ * const popup = document.createElement('div')
+ * const action = portal(popup, document.body)
+ * action.update(document.body)
+ * action.destroy()
+ * ```
  */
 export function portal(node, target = 'body') {
     function mount(to) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@h-ai/ui",
   "type": "module",
-  "version": "0.1.0-alpha.67",
+  "version": "0.1.0-alpha.68",
   "description": "Hai Framework UI component library for Svelte 5 Runes.",
   "license": "Apache-2.0",
   "svelte": "./dist/index.js",
@@ -33,10 +33,70 @@
       "svelte": "./dist/guide.js",
       "import": "./dist/guide.js"
     },
-    "./components/*": {
-      "types": "./dist/components/*.d.ts",
-      "svelte": "./dist/components/*.js",
-      "import": "./dist/components/*.js"
+    "./components/compounds/index": {
+      "types": "./dist/components/compounds/index.d.ts",
+      "svelte": "./dist/components/compounds/index.js",
+      "import": "./dist/components/compounds/index.js"
+    },
+    "./components/index": {
+      "types": "./dist/components/index.d.ts",
+      "svelte": "./dist/components/index.js",
+      "import": "./dist/components/index.js"
+    },
+    "./components/primitives/index": {
+      "types": "./dist/components/primitives/index.d.ts",
+      "svelte": "./dist/components/primitives/index.js",
+      "import": "./dist/components/primitives/index.js"
+    },
+    "./components/scenes/ai/index": {
+      "types": "./dist/components/scenes/ai/index.d.ts",
+      "svelte": "./dist/components/scenes/ai/index.js",
+      "import": "./dist/components/scenes/ai/index.js"
+    },
+    "./components/scenes/app/index": {
+      "types": "./dist/components/scenes/app/index.d.ts",
+      "svelte": "./dist/components/scenes/app/index.js",
+      "import": "./dist/components/scenes/app/index.js"
+    },
+    "./components/scenes/charts/index": {
+      "types": "./dist/components/scenes/charts/index.d.ts",
+      "svelte": "./dist/components/scenes/charts/index.js",
+      "import": "./dist/components/scenes/charts/index.js"
+    },
+    "./components/scenes/crud/index": {
+      "types": "./dist/components/scenes/crud/index.d.ts",
+      "svelte": "./dist/components/scenes/crud/index.js",
+      "import": "./dist/components/scenes/crud/index.js"
+    },
+    "./components/scenes/crypto/index": {
+      "types": "./dist/components/scenes/crypto/index.d.ts",
+      "svelte": "./dist/components/scenes/crypto/index.js",
+      "import": "./dist/components/scenes/crypto/index.js"
+    },
+    "./components/scenes/error/index": {
+      "types": "./dist/components/scenes/error/index.d.ts",
+      "svelte": "./dist/components/scenes/error/index.js",
+      "import": "./dist/components/scenes/error/index.js"
+    },
+    "./components/scenes/guide/index": {
+      "types": "./dist/components/scenes/guide/index.d.ts",
+      "svelte": "./dist/components/scenes/guide/index.js",
+      "import": "./dist/components/scenes/guide/index.js"
+    },
+    "./components/scenes/iam/index": {
+      "types": "./dist/components/scenes/iam/index.d.ts",
+      "svelte": "./dist/components/scenes/iam/index.js",
+      "import": "./dist/components/scenes/iam/index.js"
+    },
+    "./components/scenes/index": {
+      "types": "./dist/components/scenes/index.d.ts",
+      "svelte": "./dist/components/scenes/index.js",
+      "import": "./dist/components/scenes/index.js"
+    },
+    "./components/scenes/storage/index": {
+      "types": "./dist/components/scenes/storage/index.d.ts",
+      "svelte": "./dist/components/scenes/storage/index.js",
+      "import": "./dist/components/scenes/storage/index.js"
     },
     "./styles/*": "./dist/styles/*"
   },
@@ -59,7 +119,7 @@
     "svelte": "^5.57.2"
   },
   "dependencies": {
-    "@h-ai/core": "0.1.0-alpha.67",
+    "@h-ai/core": "0.1.0-alpha.68",
     "@internationalized/date": "^3.12.4",
     "@shikijs/langs": "^4.5.0",
     "bits-ui": "^2.19.5",