wms-spreadsheet 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WMS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# wms-spreadsheet
+
+Thư viện Spreadsheet cho React — giao diện giống Google Sheets, hỗ trợ **10.000+ dòng** mượt mà nhờ virtual window.
+
+## Cài đặt
+
+```bash
+npm install wms-spreadsheet
+# hoặc
+pnpm add wms-spreadsheet
+```
+
+**Peer dependencies:** `react` và `react-dom` (^18 hoặc ^19).
+
+## Sử dụng nhanh
+
+```tsx
+import { useRef } from "react";
+import {
+  Spreadsheet,
+  type ISpreadsheetColumn,
+  type ISpreadsheetRef,
+} from "wms-spreadsheet";
+import "wms-spreadsheet/style.css";
+
+const COLUMNS: ISpreadsheetColumn[] = [
+  { colName: "sku", colText: "Mã SKU", width: 120, showFilter: true },
+  { colName: "qty", colText: "SL", width: 80 },
+  { colName: "active", colText: "Kích hoạt", width: 90, meta: { type: "switch" } },
+];
+
+const INITIAL_DATA = [
+  { sku: "A001", qty: "10", active: "true" },
+  { sku: "A002", qty: "5", active: "false" },
+];
+
+function App() {
+  const sheetRef = useRef<ISpreadsheetRef>(null);
+
+  return (
+    <div style={{ width: "100%", height: "600px" }}>
+      <Spreadsheet
+        ref={sheetRef}
+        columns={COLUMNS}
+        initialData={INITIAL_DATA}
+        rowCount={1000}
+      />
+    </div>
+  );
+}
+```
+
+## Tính năng
+
+- Virtual window 2 chiều — chỉ render cell trong viewport
+- API imperative qua `ref` — `setCellValue`, `loadData`, `mergeCells`, …
+- Cell types: `text`, `select`, `multiSelect`, `boolean`, `switch`, `date`, `custom`
+- Copy/paste range (Ctrl+C / Ctrl+V), filter & sort cột, frozen columns
+- Merge cells, resize cột/hàng, đa ngôn ngữ (`locale` prop)
+
+## Tài liệu đầy đủ
+
+Xem [README trên GitHub](https://github.com/truongnguyen5x/wms-spreadsheet#readme) để biết API ref, cell meta, custom cells, locale, xử lý lỗi, v.v.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,337 @@
+import { ForwardRefExoticComponent } from 'react';
+import { ReactNode } from 'react';
+import { RefAttributes } from 'react';
+
+export declare function cellKey(row: number, col: number): string;
+
+export declare class CellStore {
+    private data;
+    private listeners;
+    getValue(row: number, col: number): string;
+    setValue(row: number, col: number, value: string): void;
+    setValues(cells: ICellStoreInput[]): void;
+    subscribe(row: number, col: number, listener: () => void): () => void;
+    getAllData(): ISheetData;
+    loadData(data: ISheetData): void;
+    clearAndLoad(data: ISheetData): void;
+    getKeys(): string[];
+    parseKey(key: string): {
+        row: number;
+        col: number;
+    };
+}
+
+export declare const COLUMN_HEADER_HEIGHT = 28;
+
+export declare function columnLabel(col: number): string;
+
+export declare type DeepPartial<T> = {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> : T[K];
+};
+
+export declare const DEFAULT_COLUMN_WIDTH = 100;
+
+export declare const DEFAULT_DATE_FORMAT = "DD/MM/YYYY";
+
+export declare const DEFAULT_OVERSCAN = 3;
+
+export declare const DEFAULT_ROW_HEIGHT = 28;
+
+export declare const DEFAULT_SPREADSHEET_LOCALE: ISpreadsheetLocale;
+
+export declare const FILTER_BLANK_VALUE = "__BLANK__";
+
+export declare interface ICellAddress {
+    row: number;
+    col: number;
+}
+
+export declare interface ICellEditorParams extends ICellRenderParams {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+    onCommit: (value: string, direction?: ICommitDirection) => void;
+    onCancel: () => void;
+}
+
+export declare interface ICellInput {
+    row: number;
+    col?: number | null;
+    colName?: string;
+    value: TCellValue;
+}
+
+export declare interface ICellMeta {
+    type?: TCellType;
+    options?: ISelectOption[];
+    /** Định dạng ngày lưu và hiển thị. Mặc định DD/MM/YYYY */
+    dateFormat?: string;
+    /** Ngày sớm nhất được chọn (chuỗi theo dateFormat của cell/cột) */
+    minDate?: string;
+    /** Ngày muộn nhất được chọn (chuỗi theo dateFormat của cell/cột) */
+    maxDate?: string;
+    customKey?: string;
+    customProps?: Record<string, unknown>;
+    invalid?: boolean;
+    disabled?: boolean;
+}
+
+export declare interface ICellMetaInput {
+    row: number;
+    col?: number | null;
+    colName?: string;
+    meta: Partial<ICellMeta>;
+}
+
+export declare interface ICellRenderParams {
+    row: number;
+    col: number;
+    value: string;
+    meta: ICellMeta;
+    isActive: boolean;
+}
+
+/** Input nội bộ cho CellStore — luôn dùng index cột. */
+declare interface ICellStoreInput {
+    row: number;
+    col: number;
+    value: string;
+}
+
+export declare interface IClipboardData {
+    range: INormalizedRange;
+    values: string[][];
+}
+
+export declare interface IColumnFilterState {
+    condition: TFilterCondition;
+    conditionValue?: string;
+    /** null = không giới hạn checkbox value. */
+    selectedValues: string[] | null;
+}
+
+export declare interface IColumnHeaderRenderParams {
+    col: number;
+    column: ISpreadsheetColumn;
+}
+
+export declare interface IColumnSortState {
+    col: number;
+    direction: TSortDirection;
+}
+
+export declare type ICommitDirection = "stay" | "down" | "right";
+
+export declare interface ICustomCellDefinition {
+    render: (params: ICellRenderParams) => ReactNode;
+    editor?: (params: ICellEditorParams) => ReactNode;
+}
+
+export declare interface IMergedRange {
+    anchorRow: number;
+    anchorCol: number;
+    rowSpan: number;
+    colSpan: number;
+}
+
+declare interface IMetaStoreInput {
+    row: number;
+    col: number;
+    meta: Partial<ICellMeta>;
+}
+
+export declare interface INormalizedRange {
+    startRow: number;
+    endRow: number;
+    startCol: number;
+    endCol: number;
+}
+
+export declare interface ISelection {
+    anchor: ICellAddress;
+    focus: ICellAddress;
+}
+
+export declare interface ISelectOption {
+    id: string;
+    label: string;
+    color?: string;
+}
+
+export declare type ISheetData = Record<string, string>;
+
+export declare interface ISpreadsheetColumn {
+    /** Key trong object data và API colName. */
+    colName: string;
+    width: number;
+    /** Text hiển thị header; mặc định colName. */
+    colText?: string;
+    /** Custom render header cell; ưu tiên hơn colText. */
+    colRender?: (params: IColumnHeaderRenderParams) => ReactNode;
+    /** Hiển thị icon/filter popup ở header cột. */
+    showFilter?: boolean;
+    /** Meta mặc định cho toàn cột; cell meta override từng field. */
+    meta?: Partial<ICellMeta>;
+    /** Căn ngang nội dung body cell. Mặc định "left". Không áp header. */
+    horizontalAlign?: THorizontalAlign;
+    /** Căn dọc nội dung body cell. Mặc định "top". Không áp header. */
+    verticalAlign?: TVerticalAlign;
+    /** Override render cell body; ưu tiên hơn registry. */
+    cellRender?: (params: ICellRenderParams) => ReactNode;
+    /** Override editor cell; ưu tiên hơn registry. */
+    cellEditor?: (params: ICellEditorParams) => ReactNode;
+}
+
+export declare interface ISpreadsheetError {
+    code: TSpreadsheetErrorCode;
+    message: string;
+}
+
+export declare interface ISpreadsheetLocale {
+    errors: {
+        mergeInvalidRange: string;
+        mergeOverlap: string;
+        mergeWhileSortFilterActive: string;
+        filterWhileMerged: string;
+        sortWhileMerged: string;
+        copyMergedNotAllowed: string;
+        pasteMergedNotAllowed: string;
+    };
+    filter: {
+        columnAriaLabel: string;
+        dialogAriaLabel: string;
+        sortAsc: string;
+        sortDesc: string;
+        filterByCondition: string;
+        filterByValue: string;
+        valuePlaceholder: string;
+        searchPlaceholder: string;
+        selectAll: string;
+        clear: string;
+        reset: string;
+        ok: string;
+        cancel: string;
+        blankCells: string;
+        conditions: Record<TFilterCondition, string>;
+    };
+    datepicker: {
+        dialogAriaLabel: string;
+        prevMonthAriaLabel: string;
+        nextMonthAriaLabel: string;
+        today: string;
+        clear: string;
+        monthNames: readonly string[];
+        weekdayLabels: readonly string[];
+    };
+}
+
+export declare interface ISpreadsheetProps {
+    rowCount: number;
+    columnCount: number;
+    columns?: ISpreadsheetColumn[];
+    rowHeight?: number;
+    /** Chiều cao hàng header cột (px). Mặc định COLUMN_HEADER_HEIGHT. */
+    colHeaderHeight?: number;
+    columnWidth?: number;
+    overscan?: number;
+    className?: string;
+    onChange?: (changes: ICellInput[]) => void;
+    onError?: (error: ISpreadsheetError) => void;
+    onColumnResize?: (col: number, width: number) => void;
+    onRowResize?: (row: number, height: number) => void;
+    initialData?: TSheetDataInput;
+    /** Số cột cố định từ trái (0 = không cố định). Ví dụ 2 → cột A, B. */
+    frozenColumnCount?: number;
+    /** Registry custom cell render/editor theo customKey. */
+    customCellRegistry?: Record<string, ICustomCellDefinition>;
+    /** UI strings; mặc định tiếng Anh. Truyền partial để override đa ngôn ngữ. */
+    locale?: DeepPartial<ISpreadsheetLocale>;
+}
+
+export declare interface ISpreadsheetRef {
+    setCellValue(row: number, col: number | null, value: TCellValue, colName?: string): void;
+    getCellValue(row: number, col: number | null, colName?: string): TCellValue;
+    setCellValues(cells: ICellInput[]): void;
+    loadData(data: TSheetDataInput): void;
+    getData(): TSheetDataOutput;
+    getRowData(row: number): TSheetRowDataOutput;
+    getActiveCell(): ICellAddress | null;
+    setActiveCell(cell: ICellAddress): void;
+    getSelection(): ISelection | null;
+    setSelection(selection: ISelection): void;
+    setCellMeta(row: number, col: number | null, meta: Partial<ICellMeta>, colName?: string): void;
+    getCellMeta(row: number, col: number | null, colName?: string): ICellMeta;
+    setCellsMeta(cells: ICellMetaInput[]): void;
+    mergeCells(range?: INormalizedRange): boolean;
+    unmergeCells(row?: number, col?: number): boolean;
+    getMergedRanges(): IMergedRange[];
+    hasMergedCells(): boolean;
+}
+
+export declare class MergeStore {
+    private anchors;
+    private coveredToAnchor;
+    private listeners;
+    private revision;
+    getRevision(): number;
+    subscribe(listener: () => void): () => void;
+    private notify;
+    getAll(): IMergedRange[];
+    hasAny(): boolean;
+    getRole(row: number, col: number): TMergeCellRole;
+    resolveAnchor(row: number, col: number): ICellAddress;
+    getSpan(row: number, col: number): {
+        rowSpan: number;
+        colSpan: number;
+    };
+    getMergeAt(row: number, col: number): IMergedRange | null;
+    rangeIntersectsMerge(range: INormalizedRange): boolean;
+    expandRange(range: INormalizedRange): INormalizedRange;
+    canMerge(range: INormalizedRange): boolean;
+    merge(range: INormalizedRange, store: CellStore, metaStore: MetaStore): boolean;
+    unmerge(row: number, col: number): boolean;
+    clear(): void;
+}
+
+export declare class MetaStore {
+    private data;
+    private listeners;
+    getMeta(row: number, col: number): ICellMeta;
+    getStoredMeta(row: number, col: number): Partial<ICellMeta>;
+    setMeta(row: number, col: number, meta: Partial<ICellMeta>): void;
+    setMetas(cells: IMetaStoreInput[]): void;
+    subscribe(row: number, col: number, listener: () => void): () => void;
+}
+
+export declare function resolveSpreadsheetLocale(partial?: DeepPartial<ISpreadsheetLocale>): ISpreadsheetLocale;
+
+export declare const ROW_HEADER_WIDTH = 46;
+
+export declare const Spreadsheet: ForwardRefExoticComponent<ISpreadsheetProps & RefAttributes<ISpreadsheetRef>>;
+
+export declare type TCellType = "text" | "select" | "multiSelect" | "boolean" | "switch" | "date" | "custom";
+
+export declare type TCellValue = string | string[];
+
+export declare type TFilterCondition = "none" | "isEmpty" | "isNotEmpty" | "isEqualTo" | "isNotEqualTo" | "beginsWith" | "endsWith" | "contains" | "doesNotContain";
+
+export declare type THorizontalAlign = "left" | "center" | "right";
+
+declare type TMergeCellRole = "anchor" | "covered" | "none";
+
+export declare type TSheetDataInput = ISheetData | string[][] | TSheetRowRecord[];
+
+export declare type TSheetDataOutput = ISheetData | TSheetRowRecord[];
+
+export declare type TSheetRowDataOutput = ISheetData | TSheetRowRecord;
+
+declare type TSheetRowRecord = Record<string, TCellValue>;
+
+export declare type TSortDirection = "asc" | "desc";
+
+export declare type TSpreadsheetErrorCode = "MERGE_COPY_NOT_ALLOWED" | "MERGE_PASTE_NOT_ALLOWED" | "MERGE_INVALID_RANGE" | "MERGE_OVERLAP" | "MERGE_SORT_FILTER_ACTIVE";
+
+export declare type TVerticalAlign = "top" | "middle" | "bottom";
+
+export { }