starry-sky-ui 0.1.0 → 0.2.0

package/dist/ChatInput/index.d.ts

@@ -20,4 +20,3 @@ export interface ChatInputProps {
  */
 declare const ChatInput: React.FC<ChatInputProps>;
 export default ChatInput;
-//# sourceMappingURL=index.d.ts.map

package/dist/ChatInput/index.js

@@ -47,4 +47,3 @@ const ChatInput = ({ onSend, loading = false, placeholder = '输入消息...', d
     return (_jsx("div", Object.assign({ className: `adui-chat-input ${isDisabled ? 'adui-chat-input-disabled' : ''} ${className}` }, { children: _jsxs("div", Object.assign({ className: "adui-chat-input-inner" }, { children: [_jsx("textarea", { ref: textareaRef, className: "adui-chat-input-textarea", value: value, onChange: handleChange, onKeyDown: handleKeyDown, placeholder: placeholder, disabled: isDisabled, rows: 1, "aria-label": "\u8F93\u5165\u804A\u5929\u6D88\u606F" }), _jsx("button", Object.assign({ className: `adui-chat-input-send ${canSend ? 'active' : ''} ${loading ? 'loading' : ''}`, onClick: handleSend, disabled: !canSend, title: loading ? '停止生成' : '发送消息', "aria-label": loading ? '停止生成' : '发送消息' }, { children: loading ? _jsx(StopIcon, {}) : _jsx(SendIcon, {}) }))] })) })));
 };
 export default ChatInput;
-//# sourceMappingURL=index.js.map

package/dist/ContentRenderer/index.d.ts

@@ -12,4 +12,3 @@ export interface ContentRendererProps {
  */
 declare const ContentRenderer: React.FC<ContentRendererProps>;
 export default ContentRenderer;
-//# sourceMappingURL=index.d.ts.map

package/dist/ContentRenderer/index.js

@@ -70,4 +70,3 @@ const CodeCopyButton = ({ code }) => {
     return (_jsx("button", Object.assign({ className: "adui-copy-btn", onClick: handleCopy, title: "\u590D\u5236\u4EE3\u7801" }, { children: copied ? (_jsx("svg", Object.assign({ width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "#4ade80", strokeWidth: "2.5", strokeLinecap: "round", strokeLinejoin: "round" }, { children: _jsx("polyline", { points: "20 6 9 17 4 12" }) }))) : (_jsxs("svg", Object.assign({ width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round" }, { children: [_jsx("rect", { x: "9", y: "9", width: "13", height: "13", rx: "2", ry: "2" }), _jsx("path", { d: "M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1" })] }))) })));
 };
 export default ContentRenderer;
-//# sourceMappingURL=index.js.map

package/dist/Input/Textarea.d.ts

@@ -43,4 +43,3 @@ export interface TextareaProps {
 }
 declare const Textarea: React.FC<TextareaProps>;
 export default Textarea;
-//# sourceMappingURL=Textarea.d.ts.map

package/dist/Input/Textarea.js

@@ -39,4 +39,3 @@ const Textarea = ({ value: valueProp, defaultValue = '', onChange, placeholder =
     return (_jsxs("div", Object.assign({ className: wrapperClass, style: style }, { children: [_jsx("textarea", { ref: textareaRef, id: id, name: name, className: "adui-textarea", value: value, placeholder: placeholder, disabled: disabled, readOnly: readOnly, maxLength: maxLength, rows: rows, onChange: handleChange, onFocus: onFocus, onBlur: onBlur, "aria-label": placeholder || name }), showCount && maxLength && (_jsx("div", Object.assign({ className: "adui-textarea-footer" }, { children: _jsx("span", Object.assign({ className: "adui-textarea-count", "aria-label": `已输入 ${value.length} 字符，最大 ${maxLength} 字符` }, { children: `${value.length}/${maxLength}` })) })))] })));
 };
 export default Textarea;
-//# sourceMappingURL=Textarea.js.map

package/dist/Input/index.d.ts

@@ -54,4 +54,3 @@ export interface InputProps {
 }
 declare const Input: React.FC<InputProps>;
 export default Input;
-//# sourceMappingURL=index.d.ts.map

package/dist/Input/index.js

@@ -84,4 +84,3 @@ const Input = ({ value: valueProp, defaultValue = '', onChange, placeholder = ''
     return (_jsxs("span", Object.assign({ className: wrapperClass, style: style }, { children: [prefix && _jsx("span", Object.assign({ className: "adui-input-prefix" }, { children: prefix })), _jsx("input", { ref: inputRef, id: id, name: name, className: "adui-input", type: inputType, value: value, placeholder: placeholder, disabled: disabled, readOnly: readOnly, maxLength: maxLength, onChange: handleChange, onKeyDown: handleKeyDown, onFocus: handleFocus, onBlur: handleBlur, autoComplete: autoComplete }), renderSuffix(), showCount && maxLength && (_jsx("span", Object.assign({ className: "adui-input-count", "aria-label": `已输入 ${value.length} 字符，最大 ${maxLength} 字符` }, { children: `${value.length}/${maxLength}` })))] })));
 };
 export default Input;
-//# sourceMappingURL=index.js.map

package/dist/Message/index.d.ts

@@ -33,4 +33,3 @@ declare const message: MessageAPI;
 declare const Message: React.FC;
 export { message };
 export default Message;
-//# sourceMappingURL=index.d.ts.map

package/dist/Message/index.js

@@ -181,4 +181,3 @@ const Message = () => {
 };
 export { message };
 export default Message;
-//# sourceMappingURL=index.js.map

package/dist/Modal/index.d.ts

@@ -54,4 +54,3 @@ export interface ModalProps {
 }
 declare const Modal: React.FC<ModalProps>;
 export default Modal;
-//# sourceMappingURL=index.d.ts.map

package/dist/Modal/index.js

@@ -96,4 +96,3 @@ const Modal = ({ open = false, onClose, onOk, onCancel, afterClose, title, child
     return (_jsxs("div", Object.assign({ className: `modal-root ${animating ? 'modal-root-enter' : ''} ${!visible ? 'modal-root-leave' : ''} ${centered ? 'modal-centered' : ''}`, style: { zIndex } }, { children: [mask && (_jsx("div", { className: `modal-mask ${animating ? 'modal-mask-enter' : ''}`, onClick: maskClosable ? handleMaskClick : undefined })), _jsx("div", Object.assign({ className: `modal-wrap ${animating ? 'modal-wrap-enter' : ''} ${centered ? 'modal-wrap-centered' : ''}`, onClick: handleMaskClick }, { children: _jsxs("div", Object.assign({ className: `modal-content ${className}`, style: Object.assign(Object.assign({}, style), { width: widthStyle, height }), role: "dialog", "aria-modal": "true" }, { children: [title && (_jsx("div", Object.assign({ className: "modal-header" }, { children: _jsx("div", Object.assign({ className: "modal-title" }, { children: title })) }))), closable && (closeButton ? (_jsx("span", Object.assign({ className: "modal-close-custom", onClick: handleCancel }, { children: closeButton }))) : (_jsx("button", Object.assign({ className: "modal-close", onClick: handleCancel, "aria-label": "Close" }, { children: "\u2715" })))), _jsx("div", Object.assign({ className: "modal-body", ref: bodyRef, style: bodyStyle }, { children: children })), renderFooter()] })) }))] })));
 };
 export default Modal;
-//# sourceMappingURL=index.js.map

package/dist/Pagination/index.d.ts

@@ -34,4 +34,3 @@ export interface PaginationProps {
 }
 declare const Pagination: React.FC<PaginationProps>;
 export default Pagination;
-//# sourceMappingURL=index.d.ts.map

package/dist/Pagination/index.js

@@ -95,4 +95,3 @@ const Pagination = ({ current: currentProp, defaultCurrent = 1, pageSize: pageSi
                     : `共 ${total} 条` }))), _jsx("button", Object.assign({ className: "pagination-btn", disabled: disabled || safeCurrent <= 1, onClick: () => changePage(safeCurrent - 1) }, { children: "\u2039" })), simple ? (_jsxs("span", Object.assign({ className: "pagination-simple-wrapper" }, { children: [_jsx("input", { className: "pagination-simple-input", type: "text", inputMode: "numeric", value: safeCurrent, disabled: disabled, onChange: handleSimpleInputChange }), _jsx("span", Object.assign({ className: "pagination-simple-sep" }, { children: "/" })), _jsx("span", Object.assign({ className: "pagination-simple-total" }, { children: totalPages }))] }))) : (pages.map((item, idx) => typeof item === 'number' ? (_jsx("button", Object.assign({ className: `pagination-btn${item === safeCurrent ? ' active' : ''}`, disabled: disabled, onClick: () => changePage(item) }, { children: item }), item)) : (_jsx("span", Object.assign({ className: "pagination-ellipsis" }, { children: "..." }), `e${idx}`)))), _jsx("button", Object.assign({ className: "pagination-btn", disabled: disabled || safeCurrent >= totalPages, onClick: () => changePage(safeCurrent + 1) }, { children: "\u203A" })), showSizeChanger && (_jsx("div", Object.assign({ className: "pagination-size-changer" }, { children: _jsx("select", Object.assign({ value: pageSize, disabled: disabled, onChange: (e) => changePageSize(Number(e.target.value)) }, { children: pageSizeOptions.map((s) => (_jsxs("option", Object.assign({ value: s }, { children: [s, " \u6761/\u9875"] }), s))) })) }))), showQuickJumper && (_jsxs("span", Object.assign({ className: "pagination-jumper-wrapper" }, { children: [_jsx("span", Object.assign({ className: "pagination-jumper-label" }, { children: "\u8DF3\u81F3" })), _jsx("input", { className: "pagination-jumper-input", type: "text", inputMode: "numeric", placeholder: "\u9875\u53F7", value: jumpValue, disabled: disabled, onChange: (e) => setJumpValue(e.target.value), onKeyDown: handleJumpKey }), _jsx("button", Object.assign({ className: "pagination-jumper-btn", disabled: disabled || !jumpValue, onClick: doJump }, { children: "\u786E\u5B9A" }))] })))] })));
 };
 export default Pagination;
-//# sourceMappingURL=index.js.map

package/dist/Select/index.d.ts

@@ -53,4 +53,3 @@ export interface SelectProps {
 }
 declare const Select: React.FC<SelectProps>;
 export default Select;
-//# sourceMappingURL=index.d.ts.map

package/dist/Select/index.js

@@ -150,4 +150,3 @@ const Select = ({ options, value: valueProp, defaultValue, onChange, placeholder
                         } })) : (_jsx("span", Object.assign({ className: `select-value ${showPlaceholder ? 'select-placeholder' : ''}` }, { children: showPlaceholder ? placeholder : selectedOption === null || selectedOption === void 0 ? void 0 : selectedOption.label }))), _jsxs("span", Object.assign({ className: "select-suffix" }, { children: [showClearIcon && (_jsx("span", Object.assign({ className: "select-clear", onClick: handleClear }, { children: "\u2715" }))), _jsx("span", Object.assign({ className: `select-arrow ${isOpen ? 'select-arrow-up' : ''}` }, { children: "\u25BC" }))] }))] })), dropdownNode] })));
 };
 export default Select;
-//# sourceMappingURL=index.js.map

package/dist/Starfield/index.d.ts

@@ -17,4 +17,3 @@ export interface StarfieldProps {
  */
 declare const Starfield: React.FC<StarfieldProps>;
 export default Starfield;
-//# sourceMappingURL=index.d.ts.map

package/dist/Starfield/index.js

@@ -36,4 +36,3 @@ const Starfield = ({ starCount = 350, starColors = ['#8b5cf6', '#3b82f6', '#ffff
     return _jsx("div", { ref: starfieldRef, className: `adui-starfield ${className}` });
 };
 export default Starfield;
-//# sourceMappingURL=index.js.map

package/dist/Table/index.d.ts

@@ -69,4 +69,3 @@ export interface TableProps<T = any> {
 }
 declare function Table<T extends Record<string, any>>(props: TableProps<T>): React.ReactElement;
 export default Table;
-//# sourceMappingURL=index.d.ts.map

package/dist/Table/index.js

@@ -189,4 +189,3 @@ function Table(props) {
                                 })] }))] })) })), renderPagination()] })));
 }
 export default Table;
-//# sourceMappingURL=index.js.map

package/dist/index.d.ts

@@ -19,4 +19,3 @@ export type { ContentRendererProps } from './ContentRenderer';
 export { default as ChatInput } from './ChatInput';
 export type { ChatInputProps } from './ChatInput';
 export type { MessageInstance as MessageType, SelectOption as SelectOptionType, ModalProps as ModalPropsType } from './types';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -8,4 +8,3 @@ export { default as Input } from './Input';
 export { default as Textarea } from './Input/Textarea';
 export { default as ContentRenderer } from './ContentRenderer';
 export { default as ChatInput } from './ChatInput';
-//# sourceMappingURL=index.js.map

package/dist/types.d.ts

@@ -9,4 +9,3 @@ import type { ContentRendererProps } from './ContentRenderer';
 import type { ChatInputProps } from './ChatInput';
 export type { SelectOption, MessageInstance, MessageOpenConfig, MessageGlobalConfig, ModalProps, ColumnType, TableProps, PaginationConfig, RowSelectionType, PaginationProps, InputProps, TextareaProps, ContentRendererProps, ChatInputProps, };
 export type { StarfieldProps } from './Starfield';
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -1,3 +1,2 @@
 // ---- AdUI 公共类型定义 ----
 export {};
-//# sourceMappingURL=types.js.map

package/dist/utils/event.d.ts

@@ -0,0 +1,50 @@
+import type { ThrottleOptions } from './types';
+/**
+ * 防抖函数
+ *
+ * 在指定延迟内连续调用只执行最后一次。
+ *
+ * @param fn - 需要防抖的函数
+ * @param delay - 延迟时间（ms），默认 300
+ * @returns 防抖后的函数
+ *
+ * @example
+ * ```ts
+ * const handleSearch = debounce((value: string) => {
+ *   fetchResults(value);
+ * }, 500);
+ * ```
+ */
+export declare function debounce<T extends (...args: any[]) => any>(fn: T, delay?: number): (...args: Parameters<T>) => void;
+/**
+ * 节流函数
+ *
+ * 在指定时间间隔内最多执行一次。
+ *
+ * @param fn - 需要节流的函数
+ * @param interval - 间隔时间（ms），默认 300
+ * @param options - 节流选项
+ * @returns 节流后的函数
+ *
+ * @example
+ * ```ts
+ * //  trailing 模式（默认）：停止触发后还会执行一次
+ * const handleScroll = throttle(() => console.log('scroll'), 200);
+ *
+ * // leading 模式：立即执行第一次
+ * const handleClick = throttle(fn, 1000, { leading: true, trailing: false });
+ * ```
+ */
+export declare function throttle<T extends (...args: any[]) => any>(fn: T, interval?: number, options?: ThrottleOptions): (...args: Parameters<T>) => void;
+/**
+ * 异步延迟
+ *
+ * @param ms - 延迟毫秒数
+ * @returns Promise
+ *
+ * @example
+ * ```ts
+ * await sleep(1000); // 等待 1 秒
+ * ```
+ */
+export declare function sleep(ms: number): Promise<void>;

package/dist/utils/event.js

@@ -0,0 +1,87 @@
+// ---- 事件/异步工具函数 ----
+/**
+ * 防抖函数
+ *
+ * 在指定延迟内连续调用只执行最后一次。
+ *
+ * @param fn - 需要防抖的函数
+ * @param delay - 延迟时间（ms），默认 300
+ * @returns 防抖后的函数
+ *
+ * @example
+ * ```ts
+ * const handleSearch = debounce((value: string) => {
+ *   fetchResults(value);
+ * }, 500);
+ * ```
+ */
+export function debounce(fn, delay = 300) {
+    let timer = null;
+    return (...args) => {
+        if (timer !== null)
+            clearTimeout(timer);
+        timer = setTimeout(() => {
+            fn(...args);
+            timer = null;
+        }, delay);
+    };
+}
+/**
+ * 节流函数
+ *
+ * 在指定时间间隔内最多执行一次。
+ *
+ * @param fn - 需要节流的函数
+ * @param interval - 间隔时间（ms），默认 300
+ * @param options - 节流选项
+ * @returns 节流后的函数
+ *
+ * @example
+ * ```ts
+ * //  trailing 模式（默认）：停止触发后还会执行一次
+ * const handleScroll = throttle(() => console.log('scroll'), 200);
+ *
+ * // leading 模式：立即执行第一次
+ * const handleClick = throttle(fn, 1000, { leading: true, trailing: false });
+ * ```
+ */
+export function throttle(fn, interval = 300, options = {}) {
+    const { leading = false, trailing = true } = options;
+    let lastTime = 0;
+    let timer = null;
+    return (...args) => {
+        const now = Date.now();
+        if (!lastTime && !leading)
+            lastTime = now;
+        const remaining = interval - (now - lastTime);
+        if (remaining <= 0) {
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            fn(...args);
+            lastTime = now;
+        }
+        else if (trailing && !timer) {
+            timer = setTimeout(() => {
+                fn(...args);
+                lastTime = Date.now();
+                timer = null;
+            }, remaining);
+        }
+    };
+}
+/**
+ * 异步延迟
+ *
+ * @param ms - 延迟毫秒数
+ * @returns Promise
+ *
+ * @example
+ * ```ts
+ * await sleep(1000); // 等待 1 秒
+ * ```
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/utils/file.d.ts

@@ -0,0 +1,68 @@
+import type { DownloadOptions } from './types';
+/**
+ * 将 Blob 转换为 base64 data URL
+ *
+ * @param blob - 源 Blob
+ * @returns base64 data URL
+ *
+ * @example
+ * ```ts
+ * const dataUrl = await blobToDataURL(blob);
+ * ```
+ */
+export declare function blobToDataURL(blob: Blob): Promise<string>;
+/**
+ * 将 base64 data URL 转换为 Blob
+ *
+ * @param dataURL - base64 data URL
+ * @returns 转换后的 Blob
+ *
+ * @example
+ * ```ts
+ * const blob = dataURLToBlob('data:image/png;base64,...');
+ * ```
+ */
+export declare function dataURLToBlob(dataURL: string): Blob;
+/**
+ * 触发文件下载
+ *
+ * @param source - 文件 URL 或 Blob
+ * @param options - 下载选项
+ *
+ * @example
+ * ```ts
+ * // 通过 URL 下载
+ * await downloadFile('/api/export/file.xlsx');
+ *
+ * // 通过 Blob 下载
+ * const blob = new Blob([data], { type: 'text/plain' });
+ * await downloadFile(blob, { filename: 'data.txt' });
+ * ```
+ */
+export declare function downloadFile(source: string | Blob, options?: DownloadOptions): Promise<void>;
+/**
+ * 读取 File 为 DataURL
+ *
+ * @param file - 文件对象
+ * @returns base64 data URL
+ *
+ * @example
+ * ```ts
+ * const dataUrl = await readFileAsDataURL(fileInput.files[0]);
+ * ```
+ */
+export declare function readFileAsDataURL(file: File): Promise<string>;
+/**
+ * 格式化文件大小为可读字符串
+ *
+ * @param bytes - 字节数
+ * @param decimals - 小数位数，默认 2
+ * @returns 格式化后的文件大小，如 "1.5 MB"
+ *
+ * @example
+ * ```ts
+ * formatFileSize(1536);      // "1.50 KB"
+ * formatFileSize(1048576, 0); // "1 MB"
+ * ```
+ */
+export declare function formatFileSize(bytes: number, decimals?: number): string;

package/dist/utils/file.js

@@ -0,0 +1,136 @@
+// ---- 文件/Blob 工具函数 ----
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+/**
+ * 将 Blob 转换为 base64 data URL
+ *
+ * @param blob - 源 Blob
+ * @returns base64 data URL
+ *
+ * @example
+ * ```ts
+ * const dataUrl = await blobToDataURL(blob);
+ * ```
+ */
+export function blobToDataURL(blob) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(reader.result);
+        reader.onerror = () => reject(new Error('Blob 读取失败'));
+        reader.readAsDataURL(blob);
+    });
+}
+/**
+ * 将 base64 data URL 转换为 Blob
+ *
+ * @param dataURL - base64 data URL
+ * @returns 转换后的 Blob
+ *
+ * @example
+ * ```ts
+ * const blob = dataURLToBlob('data:image/png;base64,...');
+ * ```
+ */
+export function dataURLToBlob(dataURL) {
+    var _a;
+    const [header, base64] = dataURL.split(',');
+    const mime = ((_a = header.match(/:(.*?);/)) === null || _a === void 0 ? void 0 : _a[1]) || '';
+    const byteStr = atob(base64);
+    const len = byteStr.length;
+    const bytes = new Uint8Array(len);
+    for (let i = 0; i < len; i++) {
+        bytes[i] = byteStr.charCodeAt(i);
+    }
+    return new Blob([bytes], { type: mime });
+}
+/**
+ * 触发文件下载
+ *
+ * @param source - 文件 URL 或 Blob
+ * @param options - 下载选项
+ *
+ * @example
+ * ```ts
+ * // 通过 URL 下载
+ * await downloadFile('/api/export/file.xlsx');
+ *
+ * // 通过 Blob 下载
+ * const blob = new Blob([data], { type: 'text/plain' });
+ * await downloadFile(blob, { filename: 'data.txt' });
+ * ```
+ */
+export function downloadFile(source, options = {}) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { filename = 'download', openInNewWindow = false } = options;
+        let url;
+        if (source instanceof Blob) {
+            url = URL.createObjectURL(source);
+        }
+        else {
+            url = source;
+        }
+        const anchor = document.createElement('a');
+        anchor.href = url;
+        anchor.download = filename;
+        anchor.style.display = 'none';
+        if (openInNewWindow && typeof source === 'string') {
+            window.open(source, '_blank');
+            return;
+        }
+        document.body.appendChild(anchor);
+        anchor.click();
+        document.body.removeChild(anchor);
+        // 如果是临时 Blob URL，释放内存
+        if (source instanceof Blob) {
+            // 给浏览器一点时间处理下载，再释放
+            setTimeout(() => URL.revokeObjectURL(url), 10000);
+        }
+    });
+}
+/**
+ * 读取 File 为 DataURL
+ *
+ * @param file - 文件对象
+ * @returns base64 data URL
+ *
+ * @example
+ * ```ts
+ * const dataUrl = await readFileAsDataURL(fileInput.files[0]);
+ * ```
+ */
+export function readFileAsDataURL(file) {
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(reader.result);
+        reader.onerror = () => reject(new Error('文件读取失败'));
+        reader.readAsDataURL(file);
+    });
+}
+/**
+ * 格式化文件大小为可读字符串
+ *
+ * @param bytes - 字节数
+ * @param decimals - 小数位数，默认 2
+ * @returns 格式化后的文件大小，如 "1.5 MB"
+ *
+ * @example
+ * ```ts
+ * formatFileSize(1536);      // "1.50 KB"
+ * formatFileSize(1048576, 0); // "1 MB"
+ * ```
+ */
+export function formatFileSize(bytes, decimals = 2) {
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const k = 1024;
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(decimals))} ${units[i]}`;
+}

package/dist/utils/image.d.ts

@@ -0,0 +1,59 @@
+import type { ImageCompressOptions } from './types';
+/**
+ * 获取图片原始尺寸与类型信息
+ *
+ * 仅读取图片元数据，不进行缩放或编码，适用于上传前预览。
+ *
+ * @param file - 图片文件
+ * @returns 图片信息（宽、高、类型）
+ *
+ * @example
+ * ```ts
+ * const info = await getImageInfo(file);
+ * // { width: 1920, height: 1080, type: 'image/jpeg' }
+ * ```
+ */
+export declare function getImageInfo(file: File | Blob): Promise<{
+    width: number;
+    height: number;
+    type: string;
+}>;
+/**
+ * 压缩/转换图片
+ *
+ * 支持缩放、格式转换、质量调节，自动检测 WebP 支持并降级。
+ *
+ * @param file - 源图片文件或 Blob
+ * @param options - 压缩选项
+ * @returns 压缩后的 Blob
+ *
+ * @example
+ * ```ts
+ * // 默认压缩（质量 0.75，最大边 1024px，自动选择 webp/jpeg）
+ * const blob = await compressImage(file);
+ *
+ * // 指定质量与尺寸
+ * const blob = await compressImage(file, { quality: 0.5, maxDimension: 800 });
+ *
+ * // 指定输出格式
+ * const blob = await compressImage(file, { format: 'image/png', forceFormat: true });
+ * ```
+ */
+export declare function compressImage(file: File | Blob, options?: ImageCompressOptions): Promise<Blob>;
+/**
+ * 纯格式转换（不缩放）
+ *
+ * 仅改变图片编码格式，保持原始尺寸不变。
+ *
+ * @param file - 源图片文件或 Blob
+ * @param targetFormat - 目标格式
+ * @param quality - 质量 (0-1)，默认 0.92
+ * @returns 转换后的 Blob
+ *
+ * @example
+ * ```ts
+ * const webpBlob = await convertImageFormat(file, 'image/webp');
+ * const jpegBlob = await convertImageFormat(file, 'image/jpeg', 0.8);
+ * ```
+ */
+export declare function convertImageFormat(file: File | Blob, targetFormat: 'image/webp' | 'image/jpeg' | 'image/png', quality?: number): Promise<Blob>;

package/dist/utils/image.js

@@ -0,0 +1,202 @@
+// ---- 图片处理工具函数 ----
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+// ==================== WebP 检测（缓存结果） ====================
+/** WebP 支持状态缓存 */
+let _webpSupported = null;
+/**
+ * 检测浏览器是否支持 WebP 格式
+ *
+ * 结果会在首次调用后缓存，避免重复创建 Canvas。
+ */
+function isWebPSupported() {
+    if (_webpSupported !== null)
+        return _webpSupported;
+    const canvas = document.createElement('canvas');
+    canvas.width = 1;
+    canvas.height = 1;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) {
+        _webpSupported = false;
+        return false;
+    }
+    ctx.fillStyle = '#fff';
+    ctx.fillRect(0, 0, 1, 1);
+    _webpSupported = canvas.toDataURL('image/webp').startsWith('data:image/webp');
+    return _webpSupported;
+}
+// ==================== 内部辅助 ====================
+/**
+ * 将图片 URL 加载为 HTMLImageElement
+ *
+ * @param url - 图片 URL（支持 blob: data: 等）
+ * @returns 加载完成的 Image 对象
+ */
+function loadImage(url) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.onload = () => resolve(img);
+        img.onerror = () => reject(new Error('图片加载失败，请检查文件是否损坏'));
+        img.src = url;
+    });
+}
+/**
+ * 确定最终的输出图片格式
+ *
+ * - 未指定格式时，优先 webp（若浏览器支持），否则 jpeg
+ * - 指定了 webp 但浏览器不支持且未强制格式时，自动降级为 jpeg
+ */
+function resolveOutputFormat(format, forceFormat) {
+    if (format) {
+        if (!forceFormat && format === 'image/webp' && !isWebPSupported()) {
+            console.warn('[compressImage] 浏览器不支持 WebP，降级为 JPEG');
+            return 'image/jpeg';
+        }
+        return format;
+    }
+    return isWebPSupported() ? 'image/webp' : 'image/jpeg';
+}
+/**
+ * 计算缩放后的目标尺寸
+ *
+ * @returns 缩放后的宽高（整数）
+ */
+function calcDimensions(width, height, maxDimension) {
+    if (maxDimension === false || maxDimension <= 0) {
+        return { width, height };
+    }
+    if (width > maxDimension || height > maxDimension) {
+        const ratio = Math.min(maxDimension / width, maxDimension / height);
+        return {
+            width: Math.round(width * ratio),
+            height: Math.round(height * ratio),
+        };
+    }
+    return { width, height };
+}
+/**
+ * 将图像绘制到 Canvas 并编码为 Blob
+ */
+function drawToBlob(img, width, height, outputFormat, quality) {
+    return new Promise((resolve, reject) => {
+        const canvas = document.createElement('canvas');
+        canvas.width = width;
+        canvas.height = height;
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+            reject(new Error('无法获取 Canvas 2D 上下文'));
+            return;
+        }
+        ctx.imageSmoothingEnabled = true;
+        // TS 类型严格模式下需要断言
+        ctx.imageSmoothingQuality = 'high';
+        ctx.drawImage(img, 0, 0, width, height);
+        canvas.toBlob((blob) => {
+            if (blob) {
+                resolve(blob);
+            }
+            else {
+                reject(new Error('Canvas 编码失败'));
+            }
+        }, outputFormat, quality);
+    });
+}
+// ==================== 公开 API ====================
+/**
+ * 获取图片原始尺寸与类型信息
+ *
+ * 仅读取图片元数据，不进行缩放或编码，适用于上传前预览。
+ *
+ * @param file - 图片文件
+ * @returns 图片信息（宽、高、类型）
+ *
+ * @example
+ * ```ts
+ * const info = await getImageInfo(file);
+ * // { width: 1920, height: 1080, type: 'image/jpeg' }
+ * ```
+ */
+export function getImageInfo(file) {
+    const objectURL = URL.createObjectURL(file);
+    return loadImage(objectURL)
+        .then((img) => ({
+        width: img.naturalWidth,
+        height: img.naturalHeight,
+        type: file.type || 'image/png',
+    }))
+        .finally(() => URL.revokeObjectURL(objectURL));
+}
+/**
+ * 压缩/转换图片
+ *
+ * 支持缩放、格式转换、质量调节，自动检测 WebP 支持并降级。
+ *
+ * @param file - 源图片文件或 Blob
+ * @param options - 压缩选项
+ * @returns 压缩后的 Blob
+ *
+ * @example
+ * ```ts
+ * // 默认压缩（质量 0.75，最大边 1024px，自动选择 webp/jpeg）
+ * const blob = await compressImage(file);
+ *
+ * // 指定质量与尺寸
+ * const blob = await compressImage(file, { quality: 0.5, maxDimension: 800 });
+ *
+ * // 指定输出格式
+ * const blob = await compressImage(file, { format: 'image/png', forceFormat: true });
+ * ```
+ */
+export function compressImage(file, options = {}) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { quality = 0.75, maxDimension = 1024, format, forceFormat = false, } = options;
+        // 确定输出格式
+        const outputFormat = resolveOutputFormat(format, forceFormat);
+        const objectURL = URL.createObjectURL(file);
+        try {
+            const img = yield loadImage(objectURL);
+            const { width, height } = calcDimensions(img.naturalWidth, img.naturalHeight, maxDimension);
+            return yield drawToBlob(img, width, height, outputFormat, quality);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`图片处理失败: ${msg}`);
+        }
+        finally {
+            URL.revokeObjectURL(objectURL);
+        }
+    });
+}
+/**
+ * 纯格式转换（不缩放）
+ *
+ * 仅改变图片编码格式，保持原始尺寸不变。
+ *
+ * @param file - 源图片文件或 Blob
+ * @param targetFormat - 目标格式
+ * @param quality - 质量 (0-1)，默认 0.92
+ * @returns 转换后的 Blob
+ *
+ * @example
+ * ```ts
+ * const webpBlob = await convertImageFormat(file, 'image/webp');
+ * const jpegBlob = await convertImageFormat(file, 'image/jpeg', 0.8);
+ * ```
+ */
+export function convertImageFormat(file, targetFormat, quality = 0.92) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return compressImage(file, {
+            format: targetFormat,
+            maxDimension: false,
+            quality,
+            forceFormat: true,
+        });
+    });
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,6 @@
+export { blobToDataURL, dataURLToBlob, downloadFile, readFileAsDataURL, formatFileSize, } from './file';
+export type { DownloadOptions } from './types';
+export { getImageInfo, compressImage, convertImageFormat, } from './image';
+export type { ImageCompressOptions } from './types';
+export { debounce, throttle, sleep, } from './event';
+export type { ThrottleOptions } from './types';

package/dist/utils/index.js

@@ -0,0 +1,7 @@
+// ---- AdUI 通用工具函数统一导出 ----
+// 文件工具
+export { blobToDataURL, dataURLToBlob, downloadFile, readFileAsDataURL, formatFileSize, } from './file';
+// 图片工具
+export { getImageInfo, compressImage, convertImageFormat, } from './image';
+// 事件工具
+export { debounce, throttle, sleep, } from './event';

package/dist/utils/types.d.ts

@@ -0,0 +1,27 @@
+/** 可选的回调函数 */
+export type Callback = () => void;
+/** 防抖/节流选项 */
+export interface ThrottleOptions {
+    /** 是否在首次调用时立即执行，默认 false */
+    leading?: boolean;
+    /** 是否在最后一次调用后延迟执行，默认 false */
+    trailing?: boolean;
+}
+/** 文件下载选项 */
+export interface DownloadOptions {
+    /** 保存的文件名（含扩展名） */
+    filename?: string;
+    /** 是否在新窗口打开，默认 false（仅 URL 下载时有效） */
+    openInNewWindow?: boolean;
+}
+/** 图片压缩/转换选项 */
+export interface ImageCompressOptions {
+    /** 压缩质量 (0-1)，默认 0.75 */
+    quality?: number;
+    /** 最大宽/高尺寸（px），设为 false 不缩放，默认 1024 */
+    maxDimension?: number | false;
+    /** 输出格式，默认根据浏览器支持自动选择 webp/jpeg */
+    format?: 'image/webp' | 'image/jpeg' | 'image/png';
+    /** 是否强制使用指定格式（不降级），默认 false */
+    forceFormat?: boolean;
+}

package/dist/utils/types.js

@@ -0,0 +1,2 @@
+// ---- AdUI 通用工具类型定义 ----
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starry-sky-ui",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "starry-sky-ui — 轻量级 React UI 组件库",
   "private": false,
   "license": "MIT",
@@ -8,10 +8,27 @@
     "type": "git",
     "url": "https://gitee.com/qqqsdx/starry-sky-ui.git"
   },
-  "keywords": ["react", "ui", "components", "typescript"],
+  "keywords": [
+    "react",
+    "ui",
+    "components",
+    "typescript"
+  ],
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./utils": {
+      "import": "./dist/utils/index.js",
+      "require": "./dist/utils/index.js",
+      "types": "./dist/utils/index.d.ts"
+    }
+  },
   "files": [
     "dist",
     "README.md"