@mogura/moguchart-plugin-excel 1.3.0

package/dist/types.d.ts

@@ -0,0 +1,110 @@
+import type { GanttRow, GanttTask } from '@mogura/moguchart-core';
+import type { ExcelLocaleDefinition } from './i18n';
+export type { ExcelLocaleDefinition };
+/**
+ * Excelエクスポート時のカスタムカラム定義
+ */
+export interface ExcelExportColumn {
+    /** カラム識別キー (例: 'wbs', 'taskName', 'start', 'end', 'progress', 'dependencies') */
+    key?: string;
+    /** Excelシートのヘッダー行に表示するラベル */
+    header: string;
+    /** 列幅 (文字数ベース。指定しない場合は自動計算) */
+    width?: number;
+    /** Excelの数値・日付表示フォーマット (例: 'yyyy/mm/dd', '0%', '#,##0') */
+    numFmt?: string;
+    /** テキストの水平配置 */
+    align?: 'left' | 'center' | 'right';
+    /** 値を独自取得・整形するためのカスタム関数 */
+    getValue?: (task: GanttTask, row: GanttRow, rowIndex: number) => any;
+}
+/**
+ * タイムライン列の刻み単位
+ */
+export type ExcelTimelineScale = 'hour' | 'day' | 'week' | 'month';
+/**
+ * Excelエクスポートの対応言語・ロケール指定
+ * - 文字列: 'ja' | 'en' | 'zh' や登録済みのロケール識別名、任意の言語コード
+ * - オブジェクト: 独自の ExcelLocaleDefinition 定義
+ */
+export type ExcelLocale = 'ja' | 'en' | 'zh' | (string & {}) | ExcelLocaleDefinition;
+/**
+ * Excelエクスポートの実行オプション
+ */
+export interface ExportExcelOptions {
+    /** 言語・ロケール ('ja' | 'en' | 'zh' 等の識別文字列、またはカスタム定義オブジェクト) */
+    locale?: ExcelLocale;
+    /** 出力ファイル名 (デフォルト: 'gantt-chart.xlsx') */
+    filename?: string;
+    /** シート名 (デフォルト: '工程表' / 英語時 'Gantt Chart') */
+    sheetName?: string;
+    /** 日付の表示形式 (デフォルト: 'YYYY/MM/DD') */
+    dateFormat?: string;
+    /** タイムラインの単位 (デフォルト: 'day') */
+    timelineScale?: ExcelTimelineScale;
+    /** 1日または1時間あたりの列数・分割数 (デフォルト: 1。スナップ単位が指定されている場合は自動計算) */
+    columnsPerUnit?: number;
+    /** スナップ単位（分）。日単位（1440, 720, 360, 180等）または時間単位（60, 30, 15等）に応じた分割列数を自動計算 */
+    snapDurationMinutes?: number;
+    /** タイムライン（カレンダー）列の幅 (文字数ベース。指定しない場合は画面表示幅またはスケール既定値から自動計算) */
+    timelineColumnWidth?: number;
+    /** タイムラインに土日を含めるか (デフォルト: true。土日列は薄いグレー背景) */
+    includeWeekends?: boolean;
+    /** 今日の日付列をハイライトするか (デフォルト: true) */
+    highlightToday?: boolean;
+    /** ヘッダーやアクセントのテーマカラー (CSS HEXカラー。デフォルト: '#3B82F6') */
+    themeColor?: string;
+    /** 祝祭日判定関数 (trueを返すと祝祭日として扱われます。未指定時はchart.option.calendar.isHolidayを自動参照) */
+    isHoliday?: (date: Date) => boolean;
+    /** 祝祭日列の背景色 (CSS HEXカラー。デフォルト: '#FEE2E2') */
+    holidayColor?: string;
+    /** タイムラインの表示開始日 (指定しない場合は全タスクの最小開始日または現在日) */
+    startDate?: Date;
+    /** タイムラインの表示終了日 (指定しない場合は全タスクの最大終了日または開始日から1ヶ月後) */
+    endDate?: Date;
+    /** 出力カラムのカスタム定義配列、または標準カラム配列を受け取ってカスタマイズする関数 (指定しない場合は標準カラムが出力されます) */
+    columns?: ExcelExportColumn[] | ((defaultColumns: ExcelExportColumn[]) => ExcelExportColumn[]);
+    /** 自動ダウンロードを実行するか (デフォルト: true。ブラウザ環境のみ有効) */
+    download?: boolean;
+}
+/**
+ * プラグイン初期化時の設定オプション
+ */
+export interface ExcelPluginConfig {
+    /** デフォルトの言語・ロケール */
+    locale?: ExcelLocale;
+    /** プラグイン初期化時に追加登録するカスタムロケール辞書 */
+    locales?: Record<string, ExcelLocaleDefinition>;
+    /** デフォルトのファイル名 */
+    defaultFilename?: string;
+    /** デフォルトのシート名 */
+    defaultSheetName?: string;
+    /** デフォルトの出力カラム定義、またはカスタマイズ関数 */
+    defaultColumns?: ExcelExportColumn[] | ((defaultColumns: ExcelExportColumn[]) => ExcelExportColumn[]);
+    /** デフォルトの日付形式 */
+    dateFormat?: string;
+    /** デフォルトのタイムライン単位 */
+    timelineScale?: ExcelTimelineScale;
+    /** デフォルトの1日/1時間あたり列数 */
+    columnsPerUnit?: number;
+    /** デフォルトのスナップ単位（分） */
+    snapDurationMinutes?: number;
+    /** デフォルトのタイムライン列幅 */
+    timelineColumnWidth?: number;
+    /** 土日を含めるか */
+    includeWeekends?: boolean;
+    /** テーマカラー */
+    themeColor?: string;
+    /** デフォルトの祝祭日判定関数 */
+    isHoliday?: (date: Date) => boolean;
+    /** デフォルトの祝祭日背景色 */
+    holidayColor?: string;
+}
+declare module '@mogura/moguchart-core' {
+    interface GanttChartElement {
+        /**
+         * ガントチャートのデータをExcel (.xlsx) 形式でエクスポートします
+         */
+        exportExcel?: (options?: ExportExcelOptions) => Promise<Blob>;
+    }
+}

package/dist/utils.d.ts

@@ -0,0 +1,124 @@
+import type { GanttChartElement, GanttRow } from '@mogura/moguchart-core';
+import type { ExcelLocale, ExcelTimelineScale, ExportExcelOptions } from './types';
+export declare const EN_MONTH_NAMES: string[];
+/**
+ * ガントチャートまたはオプションから言語・ロケールを判定する
+ */
+export declare function detectLocale(chart?: GanttChartElement, explicitLocale?: ExcelLocale): ExcelLocale;
+/**
+ * タイムライン用の単一列情報（日、月、週、時間など全スケール共通）
+ */
+export interface TimelineItem {
+    key: string;
+    startDate: Date;
+    endDate: Date;
+    groupLabel: string;
+    subLabel: string;
+    scale?: ExcelTimelineScale;
+    isWeekend?: boolean;
+    isHoliday?: boolean;
+    isToday?: boolean;
+    width?: number;
+}
+/**
+ * WBS階層情報が付加された行・タスク情報
+ */
+export interface FlatRowItem {
+    row: GanttRow;
+    wbsNumber: string;
+    depth: number;
+    isParent: boolean;
+}
+/**
+ * Excelのワークシート名として安全な名前にサニタイズする
+ * - 使用禁止文字: * ? : \ / [ ]
+ * - 最大長: 31文字
+ */
+export declare function sanitizeSheetName(name?: string, fallback?: string, maxLen?: number): string;
+/**
+ * CSSカラー文字列（HEX, rgb, rgba, 主要カラー名）をExcelJS用のARGB形式に変換する
+ * 例: '#3B82F6' -> 'FF3B82F6', 'rgb(59, 130, 246)' -> 'FF3B82F6'
+ */
+export declare function hexToArgb(color?: string, defaultArgb?: string): string;
+/**
+ * ARGB形式の色から輝度（Luminance）を計算し、視認性の高いコントラスト文字色（白または黒）を返す
+ */
+export declare function getContrastArgb(argb: string): string;
+/**
+ * タスク情報からガントチャート表示色（ARGB形式）を抽出・決定する
+ * 優先順位:
+ * 1. task.style の background-color / background
+ * 2. task.attribute.colorPalette.backgroundColor または task.colorPalette.backgroundColor
+ * 3. task.progressColor
+ * 4. task.backgroundColor または task.color
+ * 5. サマリータスクの場合は 'FF334155'、通常タスクの場合は themeArgb
+ */
+export declare function extractTaskBarColor(task: any, isParent?: boolean, themeArgb?: string): string;
+/**
+ * タイムライン列アイテム（祝祭日、土日、平日）に応じた背景色（ARGB）を返す
+ * ※ 背景色（土日・祝祭日）の適用は「日単位（scale === 'day'）」のみ行います。
+ * - 祝祭日・日曜日: holidayArgb (デフォルト: 'FFFEE2E2', 淡い赤/ピンク)
+ * - 土曜日: 'FFEFF6FF' (淡いブルー)
+ * - 平日（または日単位以外）: null (背景色なし / 白)
+ */
+export declare function getTimelineCellBgColor(item: TimelineItem, holidayArgb?: string, scale?: ExcelTimelineScale): string | null;
+/**
+ * チャートの設定やオプションから適切なタイムラインスケールを判定する
+ */
+export declare function detectTimelineScale(chart?: GanttChartElement, explicitScale?: ExcelTimelineScale): ExcelTimelineScale;
+/**
+ * ExcelJS に渡す Date オブジェクトを、ローカル時刻の見た目通りの日付シリアル値になるよう補正する。
+ * ExcelJS は内部で date.getTime() (UTC) を使用してシリアル値を計算するため、
+ * JST などの正のタイムゾーン下ではローカル日時 (例: 2025-01-01 00:00:00) が前日 (2024-12-31 15:00:00) のシリアル値として
+ * 書き込まれてしまい、Excel 上で 1日 (または月単位で 1ヶ月) 過去にずれて表示される。
+ * そのため、getTimezoneOffset() 分を差し引くことで、Excel 上のシリアル値がローカル日時と完全に一致するようにする。
+ */
+export declare function toExcelDate(date: Date): Date;
+/**
+ * タイムラインの開始日・終了日を計算し、スケール単位にスナップする
+ * 優先順位:
+ * 1. options の startDate / endDate
+ * 2. calendar (画面上のカレンダー表示設定) の start / end
+ * 3. 行・タスク全体の最小開始日 / 最大終了日
+ */
+export declare function getTimelineRange(rows: GanttRow[], options?: Pick<ExportExcelOptions, 'startDate' | 'endDate'>, scale?: ExcelTimelineScale, calendar?: {
+    start?: Date;
+    end?: Date;
+}): {
+    startDate: Date;
+    endDate: Date;
+};
+/**
+ * 画面上のピクセル幅 (px) を Excel の列幅 (文字幅単位) に変換する
+ * 一般的な Excel の標準フォント (11pt) では 1文字幅 ≒ 約7.5px
+ */
+export declare function pxToExcelColumnWidth(px: number, minWidth?: number): number;
+/**
+ * オプション、チャート設定、スケールから最適なタイムライン列幅（Excel列幅単位）を判定・算出する
+ */
+export declare function detectTimelineColumnWidth(chart?: GanttChartElement, explicitWidth?: number, scale?: ExcelTimelineScale, columnsPerUnit?: number): number;
+/**
+ * 1日または1時間あたりの分割列数を判定・算出する
+ * 優先順位:
+ * 1. options.columnsPerUnit (明示的指定)
+ * 2. options.snapDurationMinutes (スナップ分数から計算)
+ * 3. chart.option.snapDuration (チャート設定のスナップ分数から計算)
+ * 4. デフォルト: 1
+ */
+export declare function detectColumnsPerUnit(chart?: GanttChartElement, options?: Pick<ExportExcelOptions, 'columnsPerUnit' | 'snapDurationMinutes'>, scale?: ExcelTimelineScale): number;
+/**
+ * 各スケール（日・週・月・時間）に応じたタイムライン列リストを生成する
+ */
+export declare function generateTimelineList(startDate: Date, endDate: Date, scale?: ExcelTimelineScale, includeWeekends?: boolean, columnWidth?: number, columnsPerUnit?: number, isHoliday?: (date: Date) => boolean, locale?: ExcelLocale): TimelineItem[];
+/**
+ * 行リストからWBSコード（1, 1.1, 1.2 等）と階層深さを計算してフラット化する
+ */
+export declare function calculateWbsHierarchy(rows: GanttRow[]): FlatRowItem[];
+/**
+ * 曜日の表記を取得する（登録済みロケールまたはカスタム定義に対応）
+ */
+export declare function getDayOfWeekText(dayOfWeek: number, locale?: ExcelLocale): string;
+/**
+ * ブラウザ環境でBlobをファイルとしてダウンロードする
+ */
+export declare function downloadBlob(blob: Blob, filename: string): void;

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@mogura/moguchart-plugin-excel",
+  "type": "module",
+  "version": "1.3.0",
+  "description": "Excel (.xlsx) export plugin for @mogura/moguchart-core",
+  "license": "MIT",
+  "author": "Murakami Hiroyuki",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hiro-murakami/moguchart-core.git",
+    "directory": "packages/plugin-excel"
+  },
+  "homepage": "https://github.com/hiro-murakami/moguchart-core",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "gantt",
+    "moguchart",
+    "excel",
+    "xlsx",
+    "export",
+    "spreadsheet",
+    "timeline"
+  ],
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "README.ja.md"
+  ],
+  "main": "./dist/moguchart-plugin-excel.umd.js",
+  "module": "./dist/moguchart-plugin-excel.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/moguchart-plugin-excel.mjs",
+      "require": "./dist/moguchart-plugin-excel.umd.js"
+    }
+  },
+  "peerDependencies": {
+    "lit": "^3.0.0",
+    "@mogura/moguchart-core": "1.3.0"
+  },
+  "dependencies": {
+    "exceljs": "^4.4.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.12.0",
+    "jsdom": "^27.4.0",
+    "lit": "^3.3.2",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.16",
+    "@mogura/moguchart-core": "1.3.0"
+  },
+  "scripts": {
+    "build": "vite build && pnpm exec tsc -p tsconfig.build.json",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}