xlkit 1.0.5 → 1.1.0

package/README.md

@@ -73,22 +73,7 @@ await createWorkbook().addSheet(userSheet, users).save('users.xlsx');
 | `format` | `string` \| `Function` | 数値/日付のフォーマット文字列（例: `'$#,##0'`, `'yyyy-mm-dd'`）または変換関数。 |
 | `style` | `Style` \| `Function` | 列全体のスタイル、または値に応じた条件付きスタイル関数。 |
 
-### 2. 自動列幅調整 (`autoWidth`)
-
-列幅の自動計算ロジックを微調整できます。
-
-```typescript
-const sheet = defineSheet<User>({
-  // ...
-  autoWidth: {
-    padding: 4,            // デフォルト: 2
-    headerIncluded: true,  // ヘッダーの長さも考慮するか
-    charWidthConstant: 1.5 // 文字幅の係数（デフォルト: 1.2）
-  }
-});
-```
-
-### 3. 罫線 (`borders`)
+### 2. 罫線 (`borders`)
 
 シート全体の罫線プリセットを `borders` プロパティで指定できます。
 
@@ -106,35 +91,9 @@ const sheet = defineSheet<User>({
 
 個別のセルに罫線を設定したい場合は、`style` プロパティ内の `border` で詳細に指定可能です。
 
-### 4. スタイル (`style`)
+### 3. スタイル (`style`)
 
-フォント、背景色、配置などを詳細に設定できます。
-
-| プロパティ | 説明 | 型・値の例 |
-| :--- | :--- | :--- |
-| **`font`** | | |
-| `font.name` | フォント名 | `'Arial'`, `'ＭＳ Ｐゴシック'` |
-| `font.size` | フォントサイズ | `11`, `12` |
-| `font.bold` | 太字 | `true`, `false` |
-| `font.italic` | 斜体 | `true`, `false` |
-| `font.underline` | 下線 | `true`, `'single'`, `'double'` |
-| `font.strike` | 取り消し線 | `true`, `false` |
-| `font.color` | 文字色 | `'#FF0000'` (Hex), `{ argb: 'FFFF0000' }` |
-| **`fill`** | | |
-| `fill.color` | 背景色 (Solid) | `'#FFFF00'` (Hex) ※xlkit独自ショートカット |
-| `fill.type` | 塗りつぶしタイプ | `'pattern'` |
-| `fill.pattern` | パターン種類 | `'solid'`, `'darkGray'`, `'mediumGray'` |
-| **`alignment`** | | |
-| `alignment.horizontal` | 水平方向の配置 | `'left'`, `'center'`, `'right'`, `'justify'` |
-| `alignment.vertical` | 垂直方向の配置 | `'top'`, `'middle'`, `'bottom'` |
-| `alignment.wrapText` | 折り返し表示 | `true`, `false` |
-| `alignment.indent` | インデント | `1`, `2` |
-| `alignment.textRotation` | 文字の回転 | `45`, `90`, `'vertical'` |
-| **`border`** | | |
-| `border.top` | 上の罫線 | `{ style: 'thin', color: { argb: 'FF000000' } }` |
-| `border.left` | 左の罫線 | (同上) |
-| `border.bottom` | 下の罫線 | (同上) |
-| `border.right` | 右の罫線 | (同上) |
+フォント、背景色、配置などを詳細に設定できます。6桁のHexカラーコード (`#RRGGBB`) が使用可能です。
 
 ```typescript
 style: {
@@ -153,21 +112,13 @@ style: {
     wrapText: true
   },
   border: {
-    top: { style: 'thin', color: { argb: 'FF000000' } }
+    top: { style: 'thin', color: { argb: 'FF000000' } },
+    // ...
   }
 }
 ```
 
-#### スタイルの優先順位
-
-スタイルは以下の順序で適用（上書き）されます（下が優先）：
-
-1. **行定義 (`rows.style`)**: シート定義で指定した行全体のスタイル
-2. **データ行スタイル (`row.style`)**: データオブジェクトに含まれる `style` プロパティ
-3. **列定義 (`columns.style`)**: 列ごとのスタイル
-4. **条件付き列スタイル**: `columns.style` が関数の場合
-
-### 5. ヘッダー設定 (`header`)
+### 4. ヘッダー設定 (`header`)
 
 ヘッダー行のスタイルや構成をカスタマイズできます。
 
@@ -182,29 +133,20 @@ header: {
 }
 ```
 
-### 6. 行スタイル (`rows`)
- 
- 行ごとのスタイル（縞模様など）を定義できます。
- 
- ```typescript
- rows: {
-   style: (data, index) => {
-     // 偶数行に背景色をつける
-     return index % 2 === 0 ? { fill: { color: '#F0F0F0' } } : {};
-   }
- }
- ```
-
- また、データ行に `style` プロパティを含めることで、特定の行にスタイルを適用することも可能です。
-
- ```typescript
- const data = [
-   { name: 'Tom', age: 28 },
-   { name: 'Mary', age: 25, style: { fill: { color: '#FFFF00' } } }, // Maryの行は黄色背景
- ];
- ```
-
-### 7. ブラウザ環境でのダウンロード
+### 5. 行スタイル (`rows`)
+
+行ごとのスタイル（縞模様など）を定義できます。
+
+```typescript
+rows: {
+  style: (data, index) => {
+    // 偶数行に背景色をつける
+    return index % 2 === 0 ? { fill: { color: '#F0F0F0' } } : {};
+  }
+}
+```
+
+### 6. ブラウザ環境でのダウンロード
 
 ブラウザ環境では、`download()` メソッドを使って簡単にExcelファイルをダウンロードできます。
 
@@ -218,7 +160,7 @@ await createWorkbook().addSheet(sheet, data).download('output.xlsx');
 
 内部的には`saveToBuffer()`を呼び出してBlobを作成し、自動的にダウンロードを開始します。
 
-### 8. タイムアウト設定
+### 7. タイムアウト設定
 
 大量データ処理時のフリーズを防ぐため、`save()`、`saveToBuffer()`、`download()` にはデフォルトで10秒のタイムアウトが設定されています。
 
@@ -235,44 +177,6 @@ await createWorkbook().addSheet(sheet, data).download('output.xlsx', { timeout:
 
 > **推奨**: 10万行以下のデータであればデフォルト設定で問題ありません。それ以上の大量データを扱う場合は、ファイル分割やストリーミング処理を検討してください。
 
-### 9. 制約事項
-
-- **予約語**: 列の `key` に `'style'` は使用できません。これは行ごとのスタイル定義プロパティとして予約されています。
-- **シート名**: Excelの仕様により、シート名は31文字以内で、`\ / ? * [ ] :` の文字は使用できません。
-
-## 高度な使い方
-
-### 複数シートの作成
-
-メソッドチェーンを使用して、1つのワークブックに複数のシートを追加できます。
-
-```typescript
-await createWorkbook()
-  .addSheet(usersSheet, usersData)
-  .addSheet(productsSheet, productsData)
-  .save('data.xlsx');
-```
-
-### TypeScriptによる型安全性
-
-ジェネリクスを使用することで、列定義のキーを型安全に保つことができます。
-
-```typescript
-interface User {
-  id: number;
-  name: string;
-}
-
-// keyは 'id' | 'name' に型推論され、誤字を防げます
-const sheet = defineSheet<User>({
-  name: 'Users',
-  columns: [
-    { key: 'id', ... },   // OK
-    { key: 'nmae', ... }  // Error: Type '"nmae"' is not assignable to type 'keyof User'
-  ]
-});
-```
-
 ## ライセンス
 
 MIT

package/dist/Sheetflow.d.ts

@@ -1,8 +1,9 @@
-import { SheetDef } from './types';
+import { SheetConfig } from './types';
 export declare class XLKit {
     private workbook;
     constructor();
-    addSheet<T>(def: SheetDef<T>, data: T[]): XLKit;
+    addSheet(config: SheetConfig): XLKit;
+    private isCellValueWithStyle;
     save(path: string, options?: {
         timeout?: number;
     }): Promise<void>;
@@ -14,5 +15,4 @@ export declare class XLKit {
     }): Promise<void>;
 }
 export declare function createWorkbook(): XLKit;
-export declare function defineSheet<T>(def: SheetDef<T>): SheetDef<T>;
 //# sourceMappingURL=Sheetflow.d.ts.map

package/dist/Sheetflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sheetflow.d.ts","sourceRoot":"","sources":["../src/Sheetflow.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAsB,MAAM,SAAS,CAAC;AAGvD,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAmB;;IAMnC,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,KAAK;IAsTzC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBjE,YAAY,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAajE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAiBhF;AAED,wBAAgB,cAAc,IAAI,KAAK,CAEtC;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAE5D"}
+{"version":3,"file":"Sheetflow.d.ts","sourceRoot":"","sources":["../src/Sheetflow.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAA+C,MAAM,SAAS,CAAC;AAGnF,qBAAa,KAAK;IAChB,OAAO,CAAC,QAAQ,CAAmB;;IAMnC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,KAAK;IAkRpC,OAAO,CAAC,oBAAoB;IAQtB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBjE,YAAY,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAajE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBhF;AAED,wBAAgB,cAAc,IAAI,KAAK,CAEtC"}

package/dist/Sheetflow.js

@@ -5,39 +5,49 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.XLKit = void 0;
 exports.createWorkbook = createWorkbook;
-exports.defineSheet = defineSheet;
 const exceljs_1 = __importDefault(require("exceljs"));
 const style_1 = require("./utils/style");
 class XLKit {
     constructor() {
         this.workbook = new exceljs_1.default.Workbook();
     }
-    addSheet(def, data) {
+    addSheet(config) {
         // Validate Sheet Name
-        if (!def.name) {
+        if (!config.name) {
             throw new Error('Sheet name is required.');
         }
-        if (def.name.length > 31) {
-            throw new Error(`Sheet name "${def.name}" exceeds the maximum length of 31 characters.`);
+        if (config.name.length > 31) {
+            throw new Error(`Sheet name "${config.name}" exceeds the maximum length of 31 characters.`);
         }
         // Invalid characters: \ / ? * [ ] :
         const invalidChars = /[\\/?*[\]:]/;
-        if (invalidChars.test(def.name)) {
-            throw new Error(`Sheet name "${def.name}" contains invalid characters (\\ / ? * [ ] :).`);
+        if (invalidChars.test(config.name)) {
+            throw new Error(`Sheet name "${config.name}" contains invalid characters (\\ / ? * [ ] :).`);
         }
-        const sheet = this.workbook.addWorksheet(def.name);
-        // 1. Setup Columns
-        const columns = def.columns.map((col, colIndex) => {
-            let width = col.width;
-            // Validate Column Key
-            if (col.key === 'style') {
-                throw new Error("Column key 'style' is reserved for row styling and cannot be used as a column key.");
+        const sheet = this.workbook.addWorksheet(config.name);
+        const data = config.rows;
+        // Handle autoWidth
+        const autoWidthConfig = typeof config.autoWidth === 'boolean'
+            ? { enabled: config.autoWidth }
+            : config.autoWidth || {};
+        const autoWidthEnabled = autoWidthConfig.enabled !== false;
+        // 1. Setup Columns & Headers
+        const columns = config.headers.map((header, colIndex) => {
+            let width = header.width;
+            // Apply autoWidth if no width specified and autoWidth is enabled
+            if (!width && autoWidthEnabled) {
+                width = 'auto';
             }
             if (width === 'auto') {
-                let maxLen = col.header.length * (def.autoWidth?.headerIncluded !== false ? 1 : 0);
-                // Check data length (sample first 100 rows for performance if needed, currently all)
+                // Get header label text
+                const headerText = typeof header.label === 'string'
+                    ? header.label
+                    : header.label.value;
+                let maxLen = headerText.length * (autoWidthConfig.headerIncluded !== false ? 1 : 0);
+                // Check data length
                 data.forEach(row => {
-                    const val = row[col.key];
+                    const cellData = row[header.key];
+                    const val = this.isCellValueWithStyle(cellData) ? cellData.value : cellData;
                     const str = val != null ? String(val) : '';
                     // Simple full-width check: count as 2 if char code > 255
                     let len = 0;
@@ -47,124 +57,137 @@ class XLKit {
                     if (len > maxLen)
                         maxLen = len;
                 });
-                const padding = def.autoWidth?.padding ?? 2;
-                const constant = def.autoWidth?.charWidthConstant ?? 1.2;
+                const padding = autoWidthConfig.padding ?? 2;
+                const constant = autoWidthConfig.charWidthConstant ?? 1.2;
                 width = (maxLen + padding) * constant;
             }
+            // Get header label text for ExcelJS
+            const headerText = typeof header.label === 'string'
+                ? header.label
+                : header.label.value;
             return {
-                header: col.header,
-                key: String(col.key),
-                width: typeof width === 'number' ? width : 15,
-                style: col.style && typeof col.style === 'object' ? (0, style_1.mapStyle)(col.style) : undefined
+                header: headerText,
+                key: String(header.key),
+                width: typeof width === 'number' ? width : 15
             };
         });
         sheet.columns = columns;
-        // 2. Setup Headers (Multi-line support)
-        let headerRowCount = 1;
-        if (def.header?.rows) {
-            headerRowCount = def.header.rows.length;
-            // Clear default header row if we are using custom rows
-            sheet.spliceRows(1, 1);
-            def.header.rows.forEach((row, rowIndex) => {
-                const currentSheetRowIndex = rowIndex + 1;
-                const sheetRow = sheet.getRow(currentSheetRowIndex);
-                let colIndex = 1;
-                row.forEach((cellConfig) => {
-                    // Find next available cell (skip merged cells)
-                    while (sheet.getCell(currentSheetRowIndex, colIndex).isMerged) {
-                        colIndex++;
-                    }
-                    const cell = sheet.getCell(currentSheetRowIndex, colIndex);
-                    if (typeof cellConfig === 'string') {
-                        cell.value = cellConfig;
-                        colIndex++;
-                    }
-                    else {
-                        cell.value = cellConfig.value;
-                        if (cellConfig.style) {
-                            cell.style = { ...cell.style, ...(0, style_1.mapStyle)(cellConfig.style) };
-                        }
-                        const rowSpan = cellConfig.rowSpan || 1;
-                        const colSpan = cellConfig.colSpan || 1;
-                        if (rowSpan > 1 || colSpan > 1) {
-                            sheet.mergeCells(currentSheetRowIndex, colIndex, currentSheetRowIndex + rowSpan - 1, colIndex + colSpan - 1);
-                        }
-                        colIndex += colSpan;
-                    }
-                });
+        // 2. Apply Title Rows (if any)
+        if (config.title) {
+            const titleLabels = Array.isArray(config.title.label)
+                ? config.title.label
+                : [config.title.label];
+            titleLabels.forEach(titleText => {
+                const titleRow = sheet.insertRow(1, [titleText]);
+                // Merge title across all columns
+                if (config.headers.length > 1) {
+                    sheet.mergeCells(1, 1, 1, config.headers.length);
+                }
+                // Apply title style
+                if (config.title.style) {
+                    const mappedTitleStyle = (0, style_1.mapStyle)(config.title.style);
+                    titleRow.eachCell((cell) => {
+                        cell.style = { ...cell.style, ...mappedTitleStyle };
+                    });
+                }
             });
         }
-        // 3. Add Data & Apply Row Styles
-        const dataStartRow = headerRowCount + 1;
-        data.forEach((row, index) => {
-            const rowIndex = dataStartRow + index;
-            // We can't use addRow easily because it appends to the end, but we might have gaps if we messed with rows?
-            // Actually addRow is fine as long as we are consistent.
-            // But since we might have complex headers, let's be explicit with getRow to be safe or just use addRow if we know we are at the end.
-            // For safety with existing header logic, let's use explicit row rendering for data to ensure alignment.
-            const sheetRow = sheet.getRow(rowIndex);
-            def.columns.forEach((col, colIndex) => {
-                const cell = sheetRow.getCell(colIndex + 1);
-                cell.value = row[col.key];
-            });
-            // Apply row-level style from definition
-            if (def.rows?.style) {
-                const rowStyle = def.rows.style(row, index);
-                const mappedStyle = (0, style_1.mapStyle)(rowStyle);
-                sheetRow.eachCell((cell) => {
-                    cell.style = { ...cell.style, ...mappedStyle };
-                });
-            }
-            // Apply row-level style from data (if 'style' property exists)
-            if (row.style) {
-                const dataRowStyle = row.style;
-                const mappedStyle = (0, style_1.mapStyle)(dataRowStyle);
-                sheetRow.eachCell((cell) => {
-                    cell.style = { ...cell.style, ...mappedStyle };
-                });
+        // Calculate header row index (after title rows)
+        const titleRowCount = config.title
+            ? (Array.isArray(config.title.label) ? config.title.label.length : 1)
+            : 0;
+        const headerRowIndex = titleRowCount + 1;
+        // 3. Apply Header Cell Styles (from headers[].label.style)
+        const headerRow = sheet.getRow(headerRowIndex);
+        config.headers.forEach((header, colIndex) => {
+            if (typeof header.label === 'object' && header.label.style) {
+                const cell = headerRow.getCell(colIndex + 1);
+                const mappedStyle = (0, style_1.mapStyle)(header.label.style);
+                cell.style = { ...cell.style, ...mappedStyle };
             }
-            // Apply column-level conditional styles
-            def.columns.forEach((col, colIndex) => {
-                if (typeof col.style === 'function') {
-                    const cell = sheetRow.getCell(colIndex + 1);
-                    const cellStyle = col.style(row[col.key], row, index);
-                    cell.style = { ...cell.style, ...(0, style_1.mapStyle)(cellStyle) };
+        });
+        // 4. Apply Header Row Style (from styles.header)
+        if (config.styles?.header) {
+            const mappedHeaderStyle = (0, style_1.mapStyle)(config.styles.header);
+            headerRow.eachCell((cell) => {
+                cell.style = { ...cell.style, ...mappedHeaderStyle };
+            });
+        }
+        // 5. Apply styles.all to header row
+        if (config.styles?.all) {
+            const mappedAllStyle = (0, style_1.mapStyle)(config.styles.all);
+            headerRow.eachCell((cell) => {
+                cell.style = { ...mappedAllStyle, ...cell.style };
+            });
+        }
+        // 6. Add Data & Apply Styles
+        data.forEach((rowData, rowIndex) => {
+            const rowValues = {};
+            // Extract values from row data
+            config.headers.forEach(header => {
+                const cellData = rowData[header.key];
+                rowValues[header.key] = this.isCellValueWithStyle(cellData) ? cellData.value : cellData;
+            });
+            const addedRow = sheet.addRow(rowValues);
+            const excelRowIndex = headerRowIndex + rowIndex + 1;
+            // Apply styles to each cell
+            config.headers.forEach((header, colIndex) => {
+                const cell = addedRow.getCell(colIndex + 1);
+                const cellData = rowData[header.key];
+                const cellValue = this.isCellValueWithStyle(cellData) ? cellData.value : cellData;
+                // Apply styles in priority order
+                let finalStyle = {};
+                // 1. styles.all
+                if (config.styles?.all) {
+                    finalStyle = { ...finalStyle, ...(0, style_1.mapStyle)(config.styles.all) };
+                }
+                // 2. styles.body
+                if (config.styles?.body) {
+                    finalStyle = { ...finalStyle, ...(0, style_1.mapStyle)(config.styles.body) };
+                }
+                // 3. styles.column[key]
+                if (config.styles?.column?.[header.key]) {
+                    finalStyle = { ...finalStyle, ...(0, style_1.mapStyle)(config.styles.column[header.key]) };
                 }
-                if (col.format) {
-                    const cell = sheetRow.getCell(colIndex + 1);
-                    if (typeof col.format === 'string') {
-                        cell.numFmt = col.format;
+                // 4. styles.row(data, index)
+                if (config.styles?.row) {
+                    const rowStyle = config.styles.row(rowData, rowIndex);
+                    finalStyle = { ...finalStyle, ...(0, style_1.mapStyle)(rowStyle) };
+                }
+                // 5. headers[].style (object or function)
+                if (header.style) {
+                    if (typeof header.style === 'function') {
+                        const cellStyle = header.style(cellValue, rowData, rowIndex);
+                        finalStyle = { ...finalStyle, ...(0, style_1.mapStyle)(cellStyle) };
                     }
                     else {
-                        cell.value = col.format(row[col.key]);
+                        finalStyle = { ...finalStyle, ...(0, style_1.mapStyle)(header.style) };
+                    }
+                }
+                // 6. rows[].{key}.style (highest priority)
+                if (this.isCellValueWithStyle(cellData) && cellData.style) {
+                    finalStyle = { ...finalStyle, ...(0, style_1.mapStyle)(cellData.style) };
+                }
+                cell.style = finalStyle;
+                // Apply format
+                if (header.format) {
+                    if (typeof header.format === 'string') {
+                        cell.numFmt = header.format;
+                    }
+                    else {
+                        cell.value = header.format(cellValue);
                     }
                 }
             });
-            sheetRow.commit();
         });
-        // 4. Apply Header Styles (Global)
-        if (def.header?.style) {
-            const mappedHeaderStyle = (0, style_1.mapStyle)(def.header.style);
-            // Apply to all header rows
-            for (let i = 1; i <= headerRowCount; i++) {
-                const row = sheet.getRow(i);
-                row.eachCell((cell) => {
-                    // Merge with existing style (cell specific style takes precedence if we did it right, but here we are applying global header style)
-                    // Usually global header style is base, cell specific is override. 
-                    // But here we apply global AFTER. Let's apply it only if no style? 
-                    // Or just merge.
-                    cell.style = { ...mappedHeaderStyle, ...cell.style };
-                });
-            }
-        }
-        // 5. Apply Vertical Merges
-        def.columns.forEach((col, colIndex) => {
-            if (col.merge === 'vertical') {
-                let startRow = dataStartRow;
+        // 7. Apply Vertical Merges
+        config.headers.forEach((header, colIndex) => {
+            if (header.merge === 'vertical') {
+                let startRow = headerRowIndex + 1; // First data row
                 let previousValue = null;
                 // Iterate from first data row to last
                 for (let i = 0; i < data.length; i++) {
-                    const currentRowIndex = dataStartRow + i;
+                    const currentRowIndex = headerRowIndex + i + 1;
                     const cell = sheet.getCell(currentRowIndex, colIndex + 1);
                     const currentValue = cell.value;
                     if (i === 0) {
@@ -181,71 +204,14 @@ class XLKit {
                     }
                 }
                 // Handle the last group
-                const lastRowIndex = dataStartRow + data.length; // This is actually the row AFTER the last data row index if we use <
-                // Wait, loop goes 0 to length-1.
-                // If i=length-1 (last item), we check logic.
-                // We need to handle the merge AFTER the loop for the final group.
-                if (data.length > 0) {
-                    const finalRowIndex = dataStartRow + data.length - 1;
-                    if (finalRowIndex > startRow) {
-                        sheet.mergeCells(startRow, colIndex + 1, finalRowIndex, colIndex + 1);
-                    }
+                const lastRowIndex = headerRowIndex + data.length;
+                if (lastRowIndex > startRow) {
+                    sheet.mergeCells(startRow, colIndex + 1, lastRowIndex, colIndex + 1);
                 }
             }
         });
-        // 6. Apply Horizontal Merges
-        // We iterate row by row
-        for (let i = 0; i < data.length; i++) {
-            const currentRowIndex = dataStartRow + i;
-            const row = sheet.getRow(currentRowIndex);
-            let startCol = 1;
-            let previousValue = null;
-            let merging = false;
-            // We need to check which columns are candidates for horizontal merge.
-            // A simple approach: iterate columns. If current col has merge='horizontal', try to merge with next.
-            // But we need to group them.
-            for (let c = 0; c < def.columns.length; c++) {
-                const colDef = def.columns[c];
-                const currentCell = row.getCell(c + 1);
-                const currentValue = currentCell.value;
-                if (colDef.merge === 'horizontal') {
-                    if (!merging) {
-                        merging = true;
-                        startCol = c + 1;
-                        previousValue = currentValue;
-                    }
-                    else {
-                        if (currentValue !== previousValue) {
-                            // End of a merge group
-                            if ((c + 1) - 1 > startCol) {
-                                sheet.mergeCells(currentRowIndex, startCol, currentRowIndex, c);
-                            }
-                            // Start new group
-                            startCol = c + 1;
-                            previousValue = currentValue;
-                        }
-                    }
-                }
-                else {
-                    if (merging) {
-                        // End of merge group because this column is not mergeable
-                        if ((c + 1) - 1 > startCol) {
-                            sheet.mergeCells(currentRowIndex, startCol, currentRowIndex, c);
-                        }
-                        merging = false;
-                    }
-                }
-            }
-            // Check at end of row
-            if (merging) {
-                const lastCol = def.columns.length;
-                if (lastCol > startCol) {
-                    sheet.mergeCells(currentRowIndex, startCol, currentRowIndex, lastCol);
-                }
-            }
-        }
-        // 7. Apply Borders
-        if (def.borders === 'all') {
+        // 8. Apply Borders
+        if (config.borders === 'all') {
             sheet.eachRow((row) => {
                 row.eachCell((cell) => {
                     cell.border = {
@@ -257,7 +223,7 @@ class XLKit {
                 });
             });
         }
-        else if (def.borders === 'outer') {
+        else if (config.borders === 'outer') {
             const lastRow = sheet.rowCount;
             const lastCol = sheet.columnCount;
             // Top & Bottom
@@ -275,16 +241,22 @@ class XLKit {
                 rightCell.border = { ...rightCell.border, right: { style: 'thin' } };
             }
         }
-        else if (def.borders === 'header-body') {
+        else if (config.borders === 'header-body') {
             const lastCol = sheet.columnCount;
-            // Apply to the last row of the header
             for (let c = 1; c <= lastCol; c++) {
-                const headerCell = sheet.getCell(headerRowCount, c);
+                const headerCell = sheet.getCell(headerRowIndex, c);
                 headerCell.border = { ...headerCell.border, bottom: { style: 'medium' } };
             }
         }
         return this;
     }
+    isCellValueWithStyle(val) {
+        return val !== null &&
+            typeof val === 'object' &&
+            'value' in val &&
+            !Array.isArray(val) &&
+            !(val instanceof Date);
+    }
     async save(path, options) {
         if (!path || path.trim() === '') {
             throw new Error('File path cannot be empty.');
@@ -330,6 +302,3 @@ exports.XLKit = XLKit;
 function createWorkbook() {
     return new XLKit();
 }
-function defineSheet(def) {
-    return def;
-}

package/dist/types.d.ts

@@ -12,35 +12,43 @@ export interface XLStyle {
     alignment?: Partial<Alignment>;
     border?: Partial<Border> | 'all' | 'outer' | 'header-body' | 'none';
 }
-export interface ColumnDef<T> {
-    key: keyof T;
-    header: string;
+export type CellValue = any | {
+    value: any;
+    style?: XLStyle;
+};
+export interface HeaderDef {
+    key: string;
+    label: string | {
+        value: string;
+        style?: XLStyle;
+    };
     width?: number | 'auto';
-    merge?: 'vertical' | 'horizontal';
-    style?: XLStyle | ((val: any, row: T, index: number) => XLStyle);
+    merge?: 'vertical';
+    style?: XLStyle | ((val: any, row: any, index: number) => XLStyle);
     format?: string | ((val: any) => string);
 }
-export interface HeaderCell {
-    value: string;
-    colSpan?: number;
-    rowSpan?: number;
+export interface TitleConfig {
+    label: string | string[];
     style?: XLStyle;
 }
-export interface HeaderConfig {
-    rows?: (string | HeaderCell)[][];
-    style?: XLStyle;
-    borders?: 'header-body' | 'all' | 'none';
+export interface StylesConfig {
+    all?: XLStyle;
+    header?: XLStyle;
+    body?: XLStyle;
+    row?: (data: any, index: number) => XLStyle;
+    column?: {
+        [key: string]: XLStyle;
+    };
 }
-export interface SheetDef<T> {
+export interface SheetConfig {
     name: string;
-    columns: ColumnDef<T>[];
-    header?: HeaderConfig;
-    rows?: {
-        style?: (data: T, index: number) => XLStyle;
-    };
-    defaultStyle?: XLStyle;
+    headers: HeaderDef[];
+    rows: any[];
+    title?: TitleConfig;
+    styles?: StylesConfig;
     borders?: 'all' | 'outer' | 'header-body' | 'none';
-    autoWidth?: {
+    autoWidth?: boolean | {
+        enabled?: boolean;
         padding?: number;
         headerIncluded?: boolean;
         charWidthConstant?: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,QAAQ,GAAG;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC/D,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAC;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,CAAC;CACrE;AAED,MAAM,WAAW,SAAS,CAAC,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IAClC,KAAK,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;IACjE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,UAAU,CAAC,EAAE,EAAE,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,aAAa,GAAG,KAAK,GAAG,MAAM,CAAC;CAC1C;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;KAC7C,CAAC;IACF,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,CAAC;IACnD,SAAS,CAAC,EAAE;QACV,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/D,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,QAAQ,GAAG;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAC/D,IAAI,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG;QAAE,KAAK,CAAC,EAAE,QAAQ,CAAA;KAAE,CAAC;IAC5C,SAAS,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,KAAK,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,CAAC;CACrE;AAGD,MAAM,MAAM,SAAS,GAAG,GAAG,GAAG;IAC5B,KAAK,EAAE,GAAG,CAAC;IACX,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC;IACnE,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,MAAM,CAAC,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CACrC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,SAAS,EAAE,CAAC;IACrB,IAAI,EAAE,GAAG,EAAE,CAAC;IACZ,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,CAAC;IACnD,SAAS,CAAC,EAAE,OAAO,GAAG;QACpB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,cAAc,CAAC,EAAE,OAAO,CAAC;QACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xlkit",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [