@shival99/z-ui 1.9.23 → 1.9.25

package/types/shival99-z-ui-utils.d.ts

@@ -83,6 +83,51 @@ declare const zMiniSearch$: <T>(data: T[], query: string, fields: (keyof T | str
 }) => Observable<T[]>;
 declare const zDetectBrowser: () => ZBrowserInfo;
 
+/** Thông tin truy vấn dùng cho autocomplete/select tự tải dữ liệu. */
+interface ZAsyncOptionsQuery {
+    /** Từ khóa hiện tại người dùng đang nhập. */
+    keyword: string;
+    /** Trang cần tải, bắt đầu từ 1. */
+    page: number;
+    /** Số lượng option mong muốn trên mỗi trang. */
+    pageSize: number;
+}
+/** Kết quả trả về từ hàm tải option bất đồng bộ. */
+interface ZAsyncOptionsResult<TOption> {
+    /** Danh sách option của trang hiện tại. */
+    items: TOption[];
+    /** Tổng số option trên server, dùng để component tự tính còn trang tiếp theo hay không. */
+    total?: number;
+    /** Đặt trực tiếp còn dữ liệu hay không khi API không trả total. */
+    hasMore?: boolean;
+}
+/** Kiểu dữ liệu hàm load có thể trả về: sync, Promise hoặc Observable. */
+type ZAsyncOptionsLoadResult<TOption> = ZAsyncOptionsResult<TOption> | Promise<ZAsyncOptionsResult<TOption>> | Observable<ZAsyncOptionsResult<TOption>>;
+/** Hàm tải option theo keyword/page/pageSize. */
+type ZAsyncOptionsLoadFn<TOption> = (query: ZAsyncOptionsQuery) => ZAsyncOptionsLoadResult<TOption>;
+/** Config giúp component tự xử lý search, phân trang, loading và chống trùng option. */
+interface ZAsyncOptionsConfig<TOption> {
+    /** Hàm gọi API hoặc nguồn dữ liệu bất đồng bộ. */
+    load: ZAsyncOptionsLoadFn<TOption>;
+    /** Số item mỗi lần tải, mặc định 20. */
+    pageSize?: number;
+    /** Tự tải trang đầu khi dropdown mở/focus, kể cả keyword rỗng. */
+    loadOnFocus?: boolean;
+    /** Khóa chống trùng khi append trang mới, ví dụ: option => option.value.code. */
+    dedupeBy?: (option: TOption) => unknown;
+}
+
+/** Số option mặc định mỗi lần component tự gọi load. */
+declare const Z_ASYNC_OPTIONS_DEFAULT_PAGE_SIZE = 20;
+/** Chuẩn hóa kết quả sync/Promise/Observable về Observable để component xử lý thống nhất. */
+declare function zToAsyncOptionsObservable<TOption>(result: ZAsyncOptionsLoadResult<TOption>): Observable<ZAsyncOptionsResult<TOption>>;
+/** Gộp option mới vào danh sách cũ và loại bỏ phần tử trùng theo dedupeBy/default key. */
+declare function zMergeAsyncOptions<TOption>(current: TOption[], next: TOption[], dedupeBy?: ZAsyncOptionsConfig<TOption>['dedupeBy']): TOption[];
+/** Tính còn dữ liệu để load-more dựa trên hasMore, total hoặc độ dài page vừa trả về. */
+declare function zResolveAsyncOptionsHasMore<TOption>(result: ZAsyncOptionsResult<TOption>, pageSize: number, loadedCount: number): boolean;
+/** Lấy khóa ổn định cho option, hỗ trợ value là object và vẫn cho phép truyền dedupeBy riêng. */
+declare function zGetAsyncOptionKey<TOption>(option: TOption, dedupeBy?: ZAsyncOptionsConfig<TOption>['dedupeBy']): unknown;
+
 interface ZEchartsThemeOptions {
     /** Theme name (default: 'zTheme') */
     themeName?: string;
@@ -152,5 +197,5 @@ interface ZFormDebugOptions {
     logLevel?: 'error' | 'warn' | 'log';
 }
 
-export { VIETNAMESE_MAP, Z_DIVIDE_SCALE, Z_EXCEL_NUMBER_FORMAT_MAP, Z_LOCALE_MAP, zCapitalCase, zCleanObject, zConvertColorToArgb, zCreateEvent, zDebugFormInvalid, zDecodeUnicode, zDetectBrowser, zFormatNum, zFormatNumExcel, zMergeClasses, zMiniSearch, zMiniSearch$, zNoop, zNormalize, zRandomColor, zRegisterEchartsTheme, zRemoveVietnamese, zTransform, zTreeBuild, zTreeFlatten, zUuid, zValidForm };
-export type { ZBlurEventData, ZBrowserInfo, ZBrowserName, ZCapitalizeType, ZChangeEventData, ZClickEventData, ZCopyEventData, ZCutEventData, ZDblclickEventData, ZDeviceType, ZDragenterEventData, ZDragleaveEventData, ZDragoverEventData, ZDropEventData, ZEchartsThemeOptions, ZEmptyCheck, ZEvent, ZEventType, ZFocusEventData, ZFormDebugOptions, ZFormSubmitResult, ZFormatNumExcelOptions, ZFormatNumOptions, ZInputEventData, ZKeydownEventData, ZKeypressEventData, ZKeyupEventData, ZMousedownEventData, ZMouseenterEventData, ZMouseleaveEventData, ZMouseoutEventData, ZMouseoverEventData, ZMouseupEventData, ZNavigatorUABrandVersion, ZNavigatorUAData, ZNumberDivide, ZPasteEventData, ZTouchendEventData, ZTouchmoveEventData, ZTouchstartEventData };
+export { VIETNAMESE_MAP, Z_ASYNC_OPTIONS_DEFAULT_PAGE_SIZE, Z_DIVIDE_SCALE, Z_EXCEL_NUMBER_FORMAT_MAP, Z_LOCALE_MAP, zCapitalCase, zCleanObject, zConvertColorToArgb, zCreateEvent, zDebugFormInvalid, zDecodeUnicode, zDetectBrowser, zFormatNum, zFormatNumExcel, zGetAsyncOptionKey, zMergeAsyncOptions, zMergeClasses, zMiniSearch, zMiniSearch$, zNoop, zNormalize, zRandomColor, zRegisterEchartsTheme, zRemoveVietnamese, zResolveAsyncOptionsHasMore, zToAsyncOptionsObservable, zTransform, zTreeBuild, zTreeFlatten, zUuid, zValidForm };
+export type { ZAsyncOptionsConfig, ZAsyncOptionsLoadFn, ZAsyncOptionsLoadResult, ZAsyncOptionsQuery, ZAsyncOptionsResult, ZBlurEventData, ZBrowserInfo, ZBrowserName, ZCapitalizeType, ZChangeEventData, ZClickEventData, ZCopyEventData, ZCutEventData, ZDblclickEventData, ZDeviceType, ZDragenterEventData, ZDragleaveEventData, ZDragoverEventData, ZDropEventData, ZEchartsThemeOptions, ZEmptyCheck, ZEvent, ZEventType, ZFocusEventData, ZFormDebugOptions, ZFormSubmitResult, ZFormatNumExcelOptions, ZFormatNumOptions, ZInputEventData, ZKeydownEventData, ZKeypressEventData, ZKeyupEventData, ZMousedownEventData, ZMouseenterEventData, ZMouseleaveEventData, ZMouseoutEventData, ZMouseoverEventData, ZMouseupEventData, ZNavigatorUABrandVersion, ZNavigatorUAData, ZNumberDivide, ZPasteEventData, ZTouchendEventData, ZTouchmoveEventData, ZTouchstartEventData };