@libs-ui/components-spreadsheet 0.2.356-43

package/spreadsheet.indicator.d.ts

@@ -0,0 +1,123 @@
+import { BooleanNumber } from '@univerjs/core';
+/**
+ * Mapping Indicators — đánh dấu (highlight) header của các cột đã được "map" theo
+ * một nghiệp vụ bất kỳ, để người dùng nhìn thấy ngay cột nào đang gắn với field nào.
+ *
+ * Toàn bộ logic chạy trên workbook snapshot (plain JSON của Univer) — KHÔNG phụ thuộc
+ * vào instance Univer đang chạy. Vì vậy có thể gọi trước khi load, hoặc trên data đã save.
+ *
+ * Cách dùng: tự định nghĩa 1 `T_mappingIndicatorConfig` (style, prefix, scope…) rồi
+ * truyền vào cả `applyMappingIndicators` (để hiện) và `stripMappingIndicators` (để dọn
+ * trước khi gửi server). Không cần viết lại logic highlight cho từng nghiệp vụ.
+ */
+/** Một cột cần đánh dấu — chỉ cần biết sheet và vị trí cột (0-indexed). */
+export type T_indicatorTarget = {
+    sheetId: string;
+    colIndex: number;
+};
+/** Định nghĩa style highlight (đúng shape style object của Univer). */
+export type T_indicatorStyle = {
+    /** Màu nền — vd `{ rgb: '#389E0D' }` */
+    bg?: {
+        rgb: string;
+    };
+    /** Màu chữ — vd `{ rgb: '#FFFFFF' }` */
+    cl?: {
+        rgb: string;
+    };
+    /** Bold */
+    bl?: BooleanNumber;
+    /** Horizontal align (0 left, 1 right, 2 center) */
+    ht?: number;
+    /** Vertical align (0 top, 1 bottom, 2 middle) */
+    vt?: number;
+    /** Font size */
+    fs?: number;
+};
+/**
+ * Cấu hình cách highlight cột đã map. MỌI field đều optional — lib có default sẵn
+ * (xem `defaultMappingIndicatorConfig`), consumer chỉ override phần cần. Dùng chung cho
+ * cả apply & strip để đảm bảo đối xứng (đánh dấu rồi gỡ đúng style/prefix đã thêm).
+ */
+export type T_mappingIndicatorConfig = {
+    /** Key style đánh dấu cột đã map. Tự inject vào `styles` nếu chưa có. @default 'm' */
+    mappedStyleId?: string;
+    /** Định nghĩa style cho `mappedStyleId` — chỉ dùng khi cần inject lần đầu. @default xanh #389E0D, chữ trắng, bold */
+    mappedStyle?: T_indicatorStyle;
+    /** Key style header mặc định để revert về khi gỡ đánh dấu. @default 'h' */
+    defaultHeaderStyleId?: string;
+    /**
+     * Phạm vi sheet xử lý (reset trước khi đánh dấu / dọn). Bỏ trống = đọc từ dữ liệu:
+     * xử lý TẤT CẢ sheet có trong snapshot. Chỉ truyền khi muốn giới hạn để tối ưu.
+     * @default mọi sheet trong snapshot
+     */
+    scopeSheetIds?: string[];
+    /** Prefix icon thêm vào đầu header của cột đã map. @default '● ' */
+    prefix?: string;
+    /** Row index của header. @default 0 */
+    headerRowIndex?: number;
+    /** Tự co giãn width cột theo độ dài text (gồm prefix). @default true */
+    autoResize?: boolean;
+    /** Px trung bình mỗi ký tự khi auto-resize. @default 7.5 */
+    charWidth?: number;
+    /** Padding 2 bên (px) khi auto-resize. @default 16 */
+    padding?: number;
+};
+/**
+ * Config mặc định của lib — consumer có thể dùng trực tiếp hoặc spread-override:
+ * `{ ...defaultMappingIndicatorConfig(), prefix: '★ ' }`.
+ */
+export declare const defaultMappingIndicatorConfig: () => T_mappingIndicatorConfig;
+/**
+ * Đánh dấu header các cột đã map: gắn style `mappedStyleId`, thêm prefix icon và
+ * (tùy chọn) tự nới width. Tự reset các sheet trong scope trước để mapping cũ không sót lại.
+ *
+ * @param snapshot Workbook snapshot (plain JSON). Không bị mutate — trả về bản clone.
+ * @param targets  Danh sách cột cần đánh dấu (`{ sheetId, colIndex }`).
+ * @param config   Cấu hình style / prefix / scope. Bỏ trống = dùng default của lib.
+ */
+export declare const applyMappingIndicators: (snapshot: Record<string, unknown>, targets: T_indicatorTarget[], config?: T_mappingIndicatorConfig) => Record<string, unknown>;
+/**
+ * Gỡ toàn bộ indicator ('m' → default style, xóa prefix, khôi phục width) khỏi snapshot
+ * — dùng trước khi gửi workbook lên server để data sạch, không chứa style UI nội bộ.
+ *
+ * @param snapshot Workbook snapshot (plain JSON). Không bị mutate — trả về bản clone.
+ * @param config   Dùng chung config với `applyMappingIndicators` để gỡ đúng style/prefix.
+ *                 Bỏ trống = dùng default của lib.
+ */
+export declare const stripMappingIndicators: (snapshot: Record<string, unknown>, config?: T_mappingIndicatorConfig) => Record<string, unknown>;
+/**
+ * Mô tả 1 thao tác cấu trúc cột (do component phát qua `outColumnStructureChange`).
+ * `count` đã gộp trường hợp chọn NHIỀU cột cùng lúc (range span).
+ */
+export type T_columnStructureChange = {
+    /** Sheet xảy ra thao tác. */
+    sheetId: string;
+    /** Loại thao tác. */
+    type: 'insert' | 'remove' | 'move';
+    /** Cột bắt đầu bị tác động (0-indexed). Với `move` = cạnh trái khối nguồn. */
+    startColumn: number;
+    /** Số cột bị tác động (≥ 1; >1 khi chọn nhiều cột). */
+    count: number;
+    /** Cột đích (cạnh trái, toạ độ GỐC trước khi dời) — CHỈ có với `move`. */
+    toColumn?: number;
+};
+/** Chuyển colIndex (0-based) → chữ cái cột kiểu Excel: 0→'A', 25→'Z', 26→'AA'… */
+export declare const toColumnLetter: (index: number) => string;
+/**
+ * Remap colIndex của danh sách mapping theo 1 `T_columnStructureChange`.
+ * - Item khác `sheetId` giữ nguyên.
+ * - Item nằm trong vùng cột bị XÓA → loại khỏi kết quả.
+ * - Các item còn lại được dịch index cho khớp vị trí mới.
+ *
+ * Tự cập nhật cả `colLetter` (nếu item có field này) cho khớp `colIndex` mới — consumer
+ * không cần map lại thủ công.
+ *
+ * @example
+ * this.mappings.update((list) => remapColumnIndexes(list, change));
+ */
+export declare const remapColumnIndexes: <T extends {
+    sheetId: string;
+    colIndex: number;
+    colLetter?: string;
+}>(items: T[], change: T_columnStructureChange) => T[];

package/spreadsheet.locale.d.ts

@@ -0,0 +1,2 @@
+export declare const univerLocaleEn: any;
+export declare const univerLocaleVi: any;

package/spreadsheet.numfmt.d.ts

@@ -0,0 +1,24 @@
+import type { T_rangeSnapshot } from './spreadsheet.type';
+/**
+ * Re-assert highlight cho option đang chọn sau khi Univer re-render panel (React có thể xoá class).
+ * Dựa trên cờ data-numfmt-selected (do setActive đặt) — không suy diễn từ DOM label.
+ */
+export declare const syncActiveNumfmtHighlight: () => void;
+/**
+ * Thay danh sách định dạng ngày mặc định của Univer bằng các option custom (CUSTOM_DATE_PATTERNS),
+ * hiển thị dưới dạng PREVIEW trực quan. Univer render panel numfmt bằng React và không expose API
+ * nên phải thao tác DOM trực tiếp.
+ *
+ * @param getSnapshot         Lấy vùng chọn hiện tại (để áp numfmt).
+ * @param executeCmd          Chạy Univer command.
+ * @param onPatternSelected   Báo component pattern vừa chọn (Confirm) hoặc null (Cancel) để đồng bộ.
+ * @param getActiveCellFormat Đọc pattern hiện tại của cell — dùng highlight option khớp khi mở.
+ * @param clearPreview        Xoá live-preview overlay của Univer để canvas vẽ đúng model ngay.
+ * @param getSampleValue      Lấy giá trị THỰC (serial) của ô đại diện để label preview khớp dữ liệu cột;
+ *                            null → dùng SAMPLE_SERIAL mặc định.
+ * @returns hàm cleanup (gỡ mọi listener) — gọi khi teardown hoặc trước lần inject mới.
+ */
+export declare const injectCustomDateFormats: (getSnapshot: () => T_rangeSnapshot | null, executeCmd: (cmdId: string, params: unknown) => void, onPatternSelected?: (pattern: string | null) => void, getActiveCellFormat?: () => string, clearPreview?: () => void, getSampleValue?: () => number | null, onConfirm?: () => void) => {
+    cleanup: () => void;
+    resync: () => void;
+} | undefined;

package/spreadsheet.type.d.ts

@@ -0,0 +1,43 @@
+/** Ngôn ngữ hiển thị của spreadsheet (toolbar, menu, numfmt panel). */
+export type T_spreadsheet_locale = 'en' | 'vi';
+export type T_cellFormatResult = {
+    sheet: string;
+    col: string;
+    colIndex: number;
+    header: string;
+    numfmt: string;
+};
+export type T_rangeSnapshot = {
+    unitId: string;
+    subUnitId: string;
+    startRow: number;
+    endRow: number;
+    startColumn: number;
+    endColumn: number;
+};
+/**
+ * ID của từng toolbar item trong Univer.
+ * Dùng làm key trong T_toolbar_menu_config để ẩn/vô hiệu hoá item.
+ * Tìm ID thực tế bằng cách inspect attribute `data-u-command` trên DOM element.
+ */
+export type T_toolbar_item_id = 'univer.command.undo' | 'univer.command.redo' | 'sheet.command.set-once-format-painter' | 'sheet.command.set-range-bold' | 'sheet.command.set-range-italic' | 'sheet.command.set-range-underline' | 'sheet.command.set-range-stroke' | 'sheet.command.set-range-font-family' | 'sheet.command.set-range-fontsize' | 'sheet.command.set-range-text-color' | 'sheet.command.set-background-color' | 'sheet.command.set-border-basic' | 'sheet.command.set-horizontal-text-align' | 'sheet.command.set-vertical-text-align' | 'sheet.command.set-text-wrap' | 'sheet.command.set-text-rotation' | 'sheet.command.add-worksheet-merge' | 'sheet.command.add-worksheet-merge-all' | 'sheet.command.add-worksheet-merge-vertical' | 'sheet.command.add-worksheet-merge-horizontal' | 'sheet.command.remove-worksheet-merge' | 'sheet.command.numfmt.set.currency' | 'sheet.command.numfmt.add.decimal.command' | 'sheet.command.numfmt.subtract.decimal.command' | 'sheet.command.numfmt.set.percent' | 'sheet.operation.open.numfmt.panel' | 'formula-ui.operation.insert-function' | 'formula-ui.operation.more-functions' | 'sheet.menu.sheets-sort' | 'sheet.command.sort-range-asc' | 'sheet.command.sort-range-asc-ext' | 'sheet.command.sort-range-desc' | 'sheet.command.sort-range-desc-ext' | 'sheet.command.sort-range-custom' | 'sheet.command.smart-toggle-filter' | 'sheet.command.clear-filter-criteria' | 'sheet.command.re-calc-filter' | 'sheet.menu.data-validation' | 'data-validation.operation.open-validation-panel' | 'data-validation.command.addRuleAndOpen' | 'sheet.operation.open.conditional.formatting.panel' | 'sheet.menu.image' | 'sheet.command.insert-float-image' | 'sheet.command.insert-cell-image' | 'sheet.menu.print' | 'sheet.operation.print-open' | 'sheet.operation.open-print-grid-sidebar' | 'sheets-exchange-client.operation.exchange' | 'exchange-client.operation.import-xlsx' | 'exchange-client.operation.export-xlsx' | 'sheet.command.add-range-protection-from-toolbar' | 'sheet.operation.toggle-comment-panel' | 'sheet.operation.insert-hyper-link-toolbar' | 'ui.operation.open-find-dialog' | 'base-ui.operation.toggle-shortcut-panel' | 'sheet.toolbar.text-to-number';
+/**
+ * Cấu hình ẩn / vô hiệu hoá từng toolbar item.
+ * @example
+ * // Ẩn bold, italic; vô hiệu hoá sort
+ * const config: T_toolbar_menu_config = {
+ *   'sheet.command.set-range-bold':  { hidden: true },
+ *   'sheet.command.set-range-italic': { hidden: true },
+ *   'sheet.menu.sheets-sort':        { disabled: true },
+ * };
+ */
+/**
+ * Compatible với Univer's MenuConfig = Record<string, MenuItemConfig>.
+ * Dùng T_toolbar_item_id làm reference để biết các ID hợp lệ.
+ */
+export type T_toolbar_menu_config = Record<string, {
+    /** Ẩn hoàn toàn item khỏi toolbar */
+    hidden?: boolean;
+    /** Vô hiệu hoá item (hiển thị nhưng không click được) */
+    disabled?: boolean;
+}>;