@comitor/ui 1.10.0 → 2.0.0

package/dist/data-grid/use-data-grid.d.ts

@@ -0,0 +1,372 @@
+import * as _tanstack_react_virtual from '@tanstack/react-virtual';
+import * as _tanstack_react_table from '@tanstack/react-table';
+import { TableOptions, TableMeta, ColumnDef } from '@tanstack/react-table';
+import * as React from 'react';
+import { DataGridLocale } from './messages.js';
+import { CellPosition, CellUpdate, FileCellData, RowHeightValue, Direction, SearchState, ContextMenuState, PasteDialogState } from './types.js';
+import { DataGridMessages } from './messages-en.js';
+import './messages-vi.js';
+
+/**
+ * Tuỳ chọn của {@link useDataGrid} — mở rộng `TableOptions` của TanStack Table v8.
+ *
+ * Hook KHÔNG tự gọi API nào: mọi thay đổi dữ liệu đều đi ra ngoài qua callback
+ * (`onDataChange`, `onRowAdd`, `onRowsDelete`, `onFilesUpload`…) để ứng dụng tự
+ * quyết định lưu ở đâu (REST, GraphQL, state cục bộ…).
+ */
+interface UseDataGridProps<TData> extends Omit<TableOptions<TData>, "pageCount" | "getCoreRowModel"> {
+    /**
+     * Nhận MẢNG DỮ LIỆU MỚI sau mỗi lần sửa ô/dán/xoá nội dung.
+     * Ứng dụng tự setState + gọi API lưu (thường lưu lạc quan rồi rollback khi lỗi).
+     */
+    onDataChange?: (data: TData[]) => void;
+    /**
+     * Người dùng bấm "Thêm dòng" (hoặc Shift+Enter). Trả về ô cần focus sau khi thêm
+     * (`{ rowIndex, columnId }`), hoặc `null` để lưới không cuộn/focus.
+     */
+    onRowAdd?: (event?: React.MouseEvent<HTMLDivElement>) => Partial<CellPosition> | Promise<Partial<CellPosition> | null> | null;
+    /** Dán nhiều dòng hơn số dòng hiện có → thêm `count` dòng trong MỘT lần gọi API */
+    onRowsAdd?: (count: number) => void | Promise<void>;
+    /** Xoá dòng (menu chuột phải hoặc Ctrl+Backspace) — nhận cả bản ghi lẫn chỉ số dòng */
+    onRowsDelete?: (rows: TData[], rowIndices: number[]) => void | Promise<void>;
+    /** Chạy TRƯỚC khi áp dụng dữ liệu dán — dùng để gọi API bulk update nếu cần */
+    onPaste?: (updates: Array<CellUpdate>) => void | Promise<void>;
+    /**
+     * Tải tệp lên cho ô `variant: "file"`. Không truyền thì tệp chỉ nằm trong bộ nhớ
+     * trình duyệt (blob URL) và mất khi tải lại trang.
+     */
+    onFilesUpload?: (params: {
+        files: File[];
+        rowIndex: number;
+        columnId: string;
+    }) => Promise<FileCellData[]>;
+    onFilesDelete?: (params: {
+        fileIds: string[];
+        rowIndex: number;
+        columnId: string;
+    }) => void | Promise<void>;
+    /** Chiều cao dòng ban đầu (mặc định "short" = 36px) */
+    rowHeight?: RowHeightValue;
+    onRowHeightChange?: (rowHeight: RowHeightValue) => void;
+    /** Số dòng render thêm ngoài vùng nhìn thấy (mặc định 6) */
+    overscan?: number;
+    dir?: Direction;
+    /** Tự focus ô đầu tiên (hoặc ô chỉ định) khi có dữ liệu */
+    autoFocus?: boolean | Partial<CellPosition>;
+    /** Bấm chuột vào ô là chọn luôn ô đó (mặc định chỉ focus) */
+    enableSingleCellSelection?: boolean;
+    /** Bấm tiêu đề cột để chọn cả cột */
+    enableColumnSelection?: boolean;
+    /** Bật tìm trong bảng (Ctrl+F) */
+    enableSearch?: boolean;
+    /** Bật dán từ clipboard (Ctrl+V) */
+    enablePaste?: boolean;
+    /** Chỉ xem: khoá mọi thao tác sửa/xoá/dán */
+    readOnly?: boolean;
+    /**
+     * Ngôn ngữ của lưới: `"en"` (mặc định) · `"vi"`, hoặc cả một bảng chuỗi tự soạn.
+     *
+     * Giá trị này đi ra theo kết quả của hook, nên `<DataGrid {...gridProps}>` tự nhận được và tự
+     * phát xuống cây con. Hook cũng giữ một bản cho RIÊNG nó, vì toast render ở gốc app
+     * (`<Toaster />`) chứ không nằm trong cây của lưới — không có context nào ở đó để đọc.
+     *
+     * ⚠ Thanh công cụ nằm ngoài `<DataGrid>` nên KHÔNG nhận được giá trị này: bọc cả màn bằng
+     * `DataGridLocaleProvider`, hoặc truyền `locale` cho từng menu.
+     */
+    locale?: DataGridLocale | DataGridMessages;
+}
+declare function useDataGrid<TData>({ data, columns, rowHeight: rowHeightProp, overscan, dir: dirProp, initialState, locale, ...props }: UseDataGridProps<TData>): {
+    dataGridRef: React.RefObject<HTMLDivElement | null>;
+    headerRef: React.RefObject<HTMLDivElement | null>;
+    rowMapRef: React.RefObject<Map<number, HTMLDivElement>>;
+    footerRef: React.RefObject<HTMLDivElement | null>;
+    dir: "ltr" | "rtl";
+    table: _tanstack_react_table.Table<TData>;
+    tableMeta: TableMeta<TData>;
+    virtualTotalSize: number;
+    virtualItems: _tanstack_react_virtual.VirtualItem[];
+    measureElement: (node: Element | null) => void;
+    columns: ColumnDef<TData, any>[];
+    columnSizeVars: {
+        [key: string]: number;
+    };
+    searchState: SearchState | undefined;
+    searchMatchesByRow: Map<number, Set<string>> | null;
+    activeSearchMatch: CellPosition | null;
+    cellSelectionMap: Map<number, Set<string>> | null;
+    focusedCell: CellPosition | null;
+    editingCell: CellPosition | null;
+    rowHeight: RowHeightValue;
+    contextMenu: ContextMenuState;
+    pasteDialog: PasteDialogState;
+    onRowAdd: ((event?: React.MouseEvent<HTMLDivElement>) => Promise<void>) | undefined;
+    adjustLayout: boolean;
+    locale: {
+        grid: {
+            label: string;
+            addRow: string;
+        };
+        search: {
+            placeholder: string;
+            label: string;
+            prevMatch: string;
+            nextMatch: string;
+            close: string;
+            matchPosition: (index: number, total: number) => string;
+            noResults: string;
+            typeToSearch: string;
+        };
+        column: {
+            sortAsc: string;
+            sortDesc: string;
+            removeSort: string;
+            pinLeft: string;
+            unpinLeft: string;
+            pinRight: string;
+            unpinRight: string;
+            hide: string;
+            resize: (label: string) => string;
+            variant: {
+                shortText: string;
+                longText: string;
+                number: string;
+                url: string;
+                checkbox: string;
+                select: string;
+                multiSelect: string;
+                date: string;
+                file: string;
+            };
+        };
+        select: {
+            all: string;
+            row: string;
+            rowNumber: (rowNumber: number) => string;
+        };
+        contextMenu: {
+            copy: string;
+            cut: string;
+            clear: string;
+            deleteRows: string;
+        };
+        pasteDialog: {
+            title: string;
+            description: (rowsNeeded: number) => string;
+            expandTitle: string;
+            expandDescription: (rowsNeeded: number) => string;
+            keepTitle: string;
+            keepDescription: string;
+            cancel: string;
+            confirm: string;
+        };
+        rowHeight: {
+            label: string;
+            short: string;
+            medium: string;
+            tall: string;
+            extraTall: string;
+        };
+        view: {
+            trigger: string;
+            toggleColumns: string;
+            searchPlaceholder: string;
+            empty: string;
+        };
+        sort: {
+            trigger: string;
+            title: string;
+            emptyTitle: string;
+            description: string;
+            emptyDescription: string;
+            add: string;
+            reset: string;
+            remove: string;
+            drag: string;
+            fieldPlaceholder: string;
+            fieldEmpty: string;
+            asc: string;
+            desc: string;
+        };
+        filter: {
+            trigger: string;
+            title: string;
+            emptyTitle: string;
+            description: string;
+            emptyDescription: string;
+            add: string;
+            reset: string;
+            remove: string;
+            drag: string;
+            where: string;
+            and: string;
+            fieldPlaceholder: string;
+            fieldEmpty: string;
+            valuePlaceholder: string;
+            rangeStart: string;
+            rangeEnd: string;
+            pickDate: string;
+            pickRange: string;
+            optionPlaceholder: string;
+            optionEmpty: string;
+            selectedCount: (count: number) => string;
+            emptyValue: (label: string) => string;
+            operators: {
+                contains: string;
+                notContains: string;
+                equals: string;
+                notEquals: string;
+                startsWith: string;
+                endsWith: string;
+                isEmpty: string;
+                isNotEmpty: string;
+                lessThan: string;
+                lessThanOrEqual: string;
+                greaterThan: string;
+                greaterThanOrEqual: string;
+                isBetween: string;
+                dateEquals: string;
+                dateNotEquals: string;
+                before: string;
+                after: string;
+                onOrBefore: string;
+                onOrAfter: string;
+                is: string;
+                isNot: string;
+                isAnyOf: string;
+                isNoneOf: string;
+                isTrue: string;
+                isFalse: string;
+            };
+        };
+        cell: {
+            longTextPlaceholder: string;
+            optionSearchPlaceholder: string;
+            optionEmpty: string;
+            clearAll: string;
+            invalidUrlTitle: string;
+            invalidUrlDescription: string;
+        };
+        file: {
+            uploadLabel: string;
+            dropHere: string;
+            dragHere: string;
+            browse: string;
+            limits: (maxSize?: string, maxFiles?: number) => string;
+            count: (count: number) => string;
+            clearAll: string;
+            remove: string;
+            uploading: string;
+            deleting: string;
+            tooMany: (maxFiles: number) => string;
+            tooLarge: (maxSize: string) => string;
+            wrongType: string;
+            rejectedOne: (name: string) => string;
+            rejectedMany: (name: string, others: number) => string;
+            uploadFailed: (count: number) => string;
+            deleteFailed: (name: string) => string;
+            deleteFailedMany: string;
+        };
+        toast: {
+            cellsCopied: (count: number) => string;
+            copyFailed: string;
+            cellsCut: (count: number) => string;
+            cutFailed: string;
+            cellsPasted: (count: number) => string;
+            cellsPastedWithSkipped: (count: number, skipped: number) => string;
+            pasteSkipped: (skipped: number) => string;
+            pasteFailed: string;
+            cellsCleared: (count: number) => string;
+            rowsDeleted: (count: number) => string;
+            nothingToUndo: string;
+            nothingToRedo: string;
+            undone: (count: number) => string;
+            redone: (count: number) => string;
+        };
+        booleanText: {
+            checked: string;
+            unchecked: string;
+        };
+        shortcuts: {
+            trigger: string;
+            title: string;
+            description: string;
+            searchPlaceholder: string;
+            emptyTitle: string;
+            emptyDescription: string;
+            close: string;
+            groups: {
+                navigation: string;
+                selection: string;
+                editing: string;
+                search: string;
+                filtering: string;
+                sorting: string;
+                general: string;
+            };
+            keys: {
+                click: string;
+                doubleClick: string;
+            };
+            navigation: {
+                move: string;
+                nextCell: string;
+                prevCell: string;
+                firstColumn: string;
+                lastColumn: string;
+                firstRowSameColumn: string;
+                lastRowSameColumn: string;
+                firstColumnSameRow: string;
+                lastColumnSameRow: string;
+                firstCell: string;
+                lastCell: string;
+                pageUp: string;
+                pageDown: string;
+                scrollUp: string;
+                scrollDown: string;
+                scrollLeft: string;
+                scrollRight: string;
+            };
+            selection: {
+                extend: string;
+                toTop: string;
+                toBottom: string;
+                toFirstColumn: string;
+                toLastColumn: string;
+                all: string;
+                toggle: string;
+                range: string;
+                clear: string;
+            };
+            editing: {
+                start: string;
+                insertRow: string;
+                copy: string;
+                cut: string;
+                paste: string;
+                clear: string;
+                deleteRows: string;
+                undo: string;
+                redo: string;
+            };
+            search: {
+                open: string;
+                next: string;
+                prev: string;
+                close: string;
+            };
+            filtering: {
+                toggle: string;
+                remove: string;
+            };
+            sorting: {
+                toggle: string;
+                remove: string;
+            };
+            general: {
+                shortcuts: string;
+            };
+        };
+    } | "en" | "vi" | undefined;
+};
+
+export { type UseDataGridProps, useDataGrid };