From 90833ebaa7d9ab3cc962c0bc81e293aa0c2164d6 Mon Sep 17 00:00:00 2001 From: Toshiki Iga Date: Sat, 28 Mar 2026 09:11:19 +0900 Subject: [PATCH 01/30] =?UTF-8?q?=E5=A4=A7=E3=81=8D=E3=81=8F=E3=81=AA?= =?UTF-8?q?=E3=81=A3=E3=81=A6=E3=81=8D=E3=81=9F=E3=81=AE=E3=81=A7=E3=80=81?= =?UTF-8?q?local-html-tools=E3=81=8B=E3=82=89=E7=8B=AC=E7=AB=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 6 + README.md | 110 + TODO.md | 63 + lht-cmn/FEEDBACK.md | 54 + lht-cmn/LICENSE | 197 + lht-cmn/NOTICE | 11 + lht-cmn/README.md | 408 + lht-cmn/catalog/README.md | 16 + lht-cmn/catalog/catalog.css | 346 + lht-cmn/catalog/catalog.js | 150 + lht-cmn/catalog/index.html | 462 + lht-cmn/components.test.js | 630 ++ lht-cmn/css/components.css | 1049 ++ lht-cmn/js/components.js | 1659 +++ ...material-web-outlined-text-field.bundle.js | 459 + mikuproject-gap-notes.md | 298 + mikuproject-spec.md | 830 ++ mikuproject-src.html | 224 + mikuproject.html | 9521 +++++++++++++++++ package-lock.json | 2107 ++++ package.json | 19 + scripts/build-project-xlsx-sample.mjs | 52 + scripts/build-project.mjs | 86 + scripts/lib/single-html.mjs | 74 + src/css/app.css | 422 + src/js/excel-io.js | 958 ++ src/js/main.js | 923 ++ src/js/msproject-xml.js | 2216 ++++ src/js/project-xlsx.js | 506 + src/js/types.js | 5 + src/js/wbs-xlsx.js | 1074 ++ src/ts/excel-io.ts | 1191 +++ src/ts/main.ts | 1065 ++ src/ts/msproject-xml.ts | 2306 ++++ src/ts/project-xlsx.ts | 587 + src/ts/types.ts | 317 + src/ts/wbs-xlsx.ts | 1306 +++ testdata/dependency.xml | 68 + testdata/hierarchy.xml | 52 + testdata/minimal.xml | 24 + tests/mikuproject-excel-io.test.js | 452 + tests/mikuproject-main.test.js | 2754 +++++ tests/mikuproject-project-xlsx.test.js | 436 + tests/mikuproject-wbs-xlsx.test.js | 562 + 44 files changed, 36055 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 TODO.md create mode 100644 lht-cmn/FEEDBACK.md create mode 100644 lht-cmn/LICENSE create mode 100644 lht-cmn/NOTICE create mode 100644 lht-cmn/README.md create mode 100644 lht-cmn/catalog/README.md create mode 100644 lht-cmn/catalog/catalog.css create mode 100644 lht-cmn/catalog/catalog.js create mode 100644 lht-cmn/catalog/index.html create mode 100644 lht-cmn/components.test.js create mode 100644 lht-cmn/css/components.css create mode 100644 lht-cmn/js/components.js create mode 100644 lht-cmn/vendor/material-web-outlined-text-field.bundle.js create mode 100644 mikuproject-gap-notes.md create mode 100644 mikuproject-spec.md create mode 100644 mikuproject-src.html create mode 100644 mikuproject.html create mode 100644 package-lock.json create mode 100644 package.json create mode 100644 scripts/build-project-xlsx-sample.mjs create mode 100644 scripts/build-project.mjs create mode 100644 scripts/lib/single-html.mjs create mode 100644 src/css/app.css create mode 100644 src/js/excel-io.js create mode 100644 src/js/main.js create mode 100644 src/js/msproject-xml.js create mode 100644 src/js/project-xlsx.js create mode 100644 src/js/types.js create mode 100644 src/js/wbs-xlsx.js create mode 100644 src/ts/excel-io.ts create mode 100644 src/ts/main.ts create mode 100644 src/ts/msproject-xml.ts create mode 100644 src/ts/project-xlsx.ts create mode 100644 src/ts/types.ts create mode 100644 src/ts/wbs-xlsx.ts create mode 100644 testdata/dependency.xml create mode 100644 testdata/hierarchy.xml create mode 100644 testdata/minimal.xml create mode 100644 tests/mikuproject-excel-io.test.js create mode 100644 tests/mikuproject-main.test.js create mode 100644 tests/mikuproject-project-xlsx.test.js create mode 100644 tests/mikuproject-wbs-xlsx.test.js diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e0d9d14 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +.DS_Store +local-data +node_modules/ +coverage/ +*.log + diff --git a/README.md b/README.md new file mode 100644 index 0000000..ceba756 --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +# mikuproject + +`mikuproject` は、`MS Project XML` を読み込み、内部の `ProjectModel` へ変換し、再び `MS Project XML` や補助表現へ出力するためのローカル HTML ツールです。 + +`MS Project XML` を意味の基軸として扱い、`.xlsx` は確認・可視化・限定編集のための周辺表現として扱います。 + +## できること + +- `MS Project XML` の読込 +- `ProjectModel` への変換と内容確認 +- `MS Project XML` の再生成 +- Mermaid gantt テキスト生成 +- `CSV + ParentID` 生成と解析 +- 構造忠実な `Project / Tasks / Resources / Assignments / Calendars` workbook の `XLSX Export / Import` +- 表示専用の `WBS XLSX Export` + +## 現在の考え方 + +- 正本は `MS Project XML` +- 内部の中立表現は `ProjectModel` +- `.xlsx` は補助的な入出力 +- まずは意味的ラウンドトリップを優先 + +`XLSX Import` は自由編集をそのまま受け入れるのではなく、限定列の部分更新として扱います。 + +## リポジトリ構成 + +- `mikuproject.html`: 生成済みの単一 HTML アプリ +- `mikuproject-src.html`: HTML ソース +- `package.json`: Node.js ベースの開発設定 +- `src/ts/`: TypeScript ソース +- `src/js/`: ブラウザ実行用 JavaScript +- `src/css/`: アプリ用 CSS +- `tests/`: Vitest ベースのテスト +- `testdata/`: XML テストデータ +- `scripts/`: ビルド補助スクリプト +- `mikuproject-spec.md`: 現行仕様メモ +- `mikuproject-gap-notes.md`: 保持項目や互換性のギャップメモ + +## 使い方 + +もっとも簡単なのは、生成済みの [mikuproject.html](/Users/igapyon/Documents/git/mikuproject/mikuproject.html) をブラウザで開く方法です。 + +画面上では主に次の操作を行えます。 + +- `XML Import` +- `XML を解析` +- `XML を再生成` +- `XLSX Export` +- `XLSX Import` +- `WBS XLSX Export` +- `Mermaid を生成` + +## 開発 + +依存関係の導入: + +```bash +npm install +``` + +単一 HTML を再生成: + +```bash +npm run build:app +``` + +サンプル XLSX を再生成: + +```bash +npm run build:xlsx-sample +``` + +テスト実行: + +```bash +npm test +``` + +ビルドとテストをまとめて実行: + +```bash +npm run build +``` + +`npm run build` は `build:app` と `test` を順に実行します。 + +[scripts/build-project.mjs](/Users/igapyon/Documents/git/mikuproject/scripts/build-project.mjs) は `src/ts/` から `src/js/` を生成し、[mikuproject-src.html](/Users/igapyon/Documents/git/mikuproject/mikuproject-src.html) をもとに [mikuproject.html](/Users/igapyon/Documents/git/mikuproject/mikuproject.html) を再生成します。 + +## 現在の状態 + +- `package.json` と `package-lock.json` を持つ単独の Node.js プロジェクトとして扱える +- ソース配置は `src/ts/`, `src/js/`, `src/css/` +- `npm run build:app` と `npm test` は通る +- `local-data/` と `node_modules/` は Git 管理対象外 + +## 制約 + +- `MS Project` 実機は未保有 +- 目標は XML の完全一致ではなく、意味的に往復できること +- `XLSX Import` の反映対象は限定列のみ +- `Calendars` の `WeekDays / Exceptions / WorkWeeks` などは現時点では反映対象外 +- Mermaid の SVG プレビューは、Mermaid ランタイムが読み込まれている環境を前提とする + +## 関連ドキュメント + +- [mikuproject-spec.md](/Users/igapyon/Documents/git/mikuproject/mikuproject-spec.md) +- [mikuproject-gap-notes.md](/Users/igapyon/Documents/git/mikuproject/mikuproject-gap-notes.md) +- [TODO.md](/Users/igapyon/Documents/git/mikuproject/TODO.md) +- [LICENSE](/Users/igapyon/Documents/git/mikuproject/LICENSE) diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..9400804 --- /dev/null +++ b/TODO.md @@ -0,0 +1,63 @@ +# TODO + +## mikuproject + +- `MS Project XML` を意味の基軸として扱う +- `ProjectModel` を内部の中立表現として扱う +- `.xlsx` は確認・可視化・帳票化のための周辺表現として扱う +- `.xlsx` 編集結果を `ProjectModel` へ戻し、必要に応じて `MS Project XML` へ再出力できる構成を目指す +- `MS Project XML` を中心に据えたまま、`.xlsx` 入出力を追加する +- `.xlsx` の正本化は避け、内部モデル `ProjectModel` を中心に扱う +- まずは `.xlsx export` を優先し、`ProjectModel -> .xlsx` を成立させる +- その後に `.xlsx import` を検討し、`.xlsx -> ProjectModel` を設計する +- `.xlsx` は、構造忠実な汎用 workbook と、表示専用の WBS workbook を分けて扱う +- 初期検討時のみ `local-data/WBS_Template_analysis.md` を参照し、その後は依存しない +- `mikuproject-spec.md` に `.xlsx` 対応方針を追記する +- `.xlsx` 入出力で保持する最小フィールド集合を定義する +- `mikuproject-spec.md` では、現在の editable 列 coverage をシート別の一覧で追えるように保つ +- round-trip の観点で、`xml -> model -> xlsx` と `xlsx -> model -> xml` の扱いを切り分ける +- `.xlsx import` では編集可能な列を限定し、部分更新として `ProjectModel` へ反映する +- まずは `Tasks` シートを起点に、限定列 import を成立させる +- `Start / Finish / PercentComplete / PercentWorkComplete` など、戻しやすい項目から優先対応する +- `Tasks` で import 実績を作った後に `Resources / Assignments` へ対象を広げる +- `Resources` では `Name / Group / MaxUnits` などの戻しやすい項目から優先対応する +- `Assignments` では `Units / Work / PercentWorkComplete` などの戻しやすい項目から優先対応する +- `Project` シートでは `Name / Title / Author / Company / StartDate / FinishDate / CurrentDate / StatusDate / CalendarUID / MinutesPerDay / MinutesPerWeek / DaysPerMonth / ScheduleFromStart` を限定 import 対象として扱う +- `Calendars` シートでは、まず `Name / IsBaseCalendar / BaseCalendarUID` のみを限定 import 対象として扱う +- 複雑な `Calendar / Baseline / TimephasedData / ExtendedAttributes` は後段で扱う +- `.xlsx` 対応用のテストデータとテスト戦略を追加する +- `ProjectModel -> workbook -> .xlsx -> workbook -> ProjectModel` の統合経路を継続的に確認する +- `project-xlsx.ts` で `ProjectModel -> XlsxWorkbookModel` の変換方針を詰める +- `project-xlsx.ts` で結合セルを使う箇所を設計する +- `Project` シートに結合付きの見出し行やセクション見出しを追加する +- `Tasks / Resources / Assignments / Calendars` シートのレイアウト方針を整理する +- 上記シート粒度が `MS Project XML` / `ProjectModel` の構造に由来することを明記する +- Excel 側の独自都合ではなく、まずは `MS Project XML` の構造に忠実な workbook 構成を優先する +- WBS 帳票的な見せ方は、別ビュー・別 workbook として export を継続改善する +- `WBS XLSX Export` は表示専用 workbook として、上部サマリ、凡例、Week/BaseDate ガイド、日付帯の視認性改善を継続する +- `WBS XLSX Export` では、`ProjectModel` 由来の既定祝日と、UI から入力した追加祝日を分けて扱えるように保つ +- WBS sample 生成では、`Calendar.Exceptions` のうち非稼働日例外を祝日候補として日付帯へ反映する +- `build-project-xlsx-sample.mjs` を静的 workbook 直書きから `project-xlsx.ts` 利用へ切り替える +- `MS Project XML -> ProjectModel -> XlsxWorkbookModel -> .xlsx` のサンプル生成経路へ寄せる +- UI 上で `.xlsx import` の反映件数と差分要約を分かるようにする +- 次は `.xlsx import` の差分要約を、行単位またはシート単位でさらに見やすく整理する +- 次は `Resources / Assignments` の import 差分も UI 上で追いやすくする +- `.xlsx import` の差分要約は、同一行の複数変更を1ブロックで見せる +- 次はシート別の件数表示や、更新対象ごとの折りたたみなし一覧を検討する +- `.xlsx import` の差分要約には、`Tasks / Resources / Assignments` の件数も先頭表示する +- 次は変更が 0 件だったシートをどこまで表示するかを整理する +- 変更があったシートを前面に出し、変更なしのシートは補助表示へ下げる +- 次は `Resources / Assignments` にも変更があるケースの UI 表示確認を追加する +- 画面上の `.xlsx import` 説明文は、実際の編集可能列と差分要約の見え方に合わせて保守する +- 次は `Tasks.Start / Finish` のような日付変更が UI 差分要約で分かることを固定する +- `.xlsx import` 後に、更新済み XML を `XML Export` で保存できる導線を画面上で分かるようにする +- `.xlsx import` で変更が 0 件だった場合は、XML が未変更であることを明示する +- 対象外列や未対応シートを編集しても反映しないことを、画面文言とテストで明確にする +- `Calendars` の `WeekDays / Exceptions / WorkWeeks` は、当面は反映対象外として扱う +- 現在の editable 列 coverage を保ちながら、次段でどのシート・列を import 対象に広げるかを整理する +- 画面上の `.xlsx import` 説明は、`反映対象` と `現在は反映しないもの` を分けて読めるように保つ +- 次は `Calendars` など未対応シートを本当に import 対象へ広げるか、引き続き無視対象に留めるかを整理する +- `.xlsx import` 後に validation メッセージが必要なケースも UI テストで固定する +- `Calendars.BaseCalendarUID` のような参照系 warning も、`.xlsx import` の差分要約と validation を並べて確認できるように保つ +- `.xlsx import` による `Start > Finish` のような日付整合性エラーも UI テストで固定する +- validation が残る状態でも `XML Export` でその時点の XML を保存できることをテストで固定する diff --git a/lht-cmn/FEEDBACK.md b/lht-cmn/FEEDBACK.md new file mode 100644 index 0000000..deb3c6c --- /dev/null +++ b/lht-cmn/FEEDBACK.md @@ -0,0 +1,54 @@ +# lht-cmn Feedback + +## 2026-03-08 `lht-command-block` style contract gap + +- 症状: + - `lht-command-block` をページ側で利用しても、`lht-cmn/css/components.css` だけでは「角丸四角の結果表示ブロック」として視覚的に完成しない + - 実際には `md-code-block` / `md-code` / `md-copy-button` / `md-icon-button.md-copy-button` 相当の見た目をページ側 CSS が別途持っている前提になっている +- 問題: + - `lht-command-block` を共通部品として使っても、利用ページごとに結果表示の見た目が欠けうる + - `lht-cmn` の self-contained 方針とずれている +- 期待: + - `lht-command-block` は `lht-cmn/css/components.css` だけで最低限の完成した見た目になるべき + - 少なくとも以下の visual contract は `lht-cmn` 側に同梱する + - `.md-code-block` + - `.md-code` + - `.md-copy-button` + - `md-icon-button.md-copy-button` + - `md-icon-button.md-copy-button--surface` +- 補足: + - 今回 `docs/prompt/prompt-gen-src.html` では、既存画面に合わせるためページ側へ上記スタイルを追加して回避した + - 根本対応は `lht-cmn` 側で行うべき + +## 2026-03-08 `lht-switch-help` material bundle gap + +- 症状: + - `lht-switch-help` を利用しても、ページ側で `md-switch` が未登録のため fallback 実装に落ちる + - `prompt-gen` では text field は Material 表示なのに switch だけ fallback 表示になる +- 問題: + - `lht-*` を使っても、入力部品ごとに Material / fallback が混在しやすい + - ページ側から見ると `lht-switch-help` の見た目が他の Material 部品と揃わず、利用側で原因が見えにくい +- 期待: + - `lht-switch-help` も `lht-cmn` 側で Material 実装を self-contained に利用できる形に寄せたい + - 少なくとも `md-switch` 用 bundle の vendor / 読み込み導線を `lht-cmn` 側で用意したい + - それが難しい場合でも、README に「switch は fallback 前提になりうる」ことを明記したい +- 補足: + - 現状の `lht-switch-help` は `window.customElements.get("md-switch")` が false のとき fallback DOM を生成する実装になっている + - `lht-cmn/vendor` には `material-web-outlined-text-field.bundle.js` はあるが、`md-switch` 相当の bundle は見当たらない + +## 2026-03-09 `lht-text-field-help` trailing action gap + +- 症状: + - `prompt-gen` で「やりたいこと」入力欄に `×` クリアボタンを付けたかったが、`lht-text-field-help` 自体には trailing action / trailing icon を安全に差し込む契約がない + - 外付け absolute 配置では、Material 側の見た目中心と合いにくく、位置合わせが不安定だった +- 問題: + - 画面ごとに似た「入力クリア」「末尾アイコン」「補助アクション」実装が再発しやすい + - `lht-text-field-help` を使っていても、入力欄内アクションはページ側の局所 CSS に依存しやすい + - fallback 実装と Material 実装で、末尾アクションの見た目や余白が揃いにくい +- 期待: + - `lht-text-field-help` に trailing action slot、または `clearable` のような共通機能を検討したい + - もし汎用化しない場合でも、「入力欄右端に後付けアクションを重ねる時の推奨パターン」を README に明記したい +- 補足: + - 今回は暫定対応として `lht-text-field-help` に `clearable` 属性をローカル追加し、`prompt-gen` ではそれを利用する形へ寄せた + - ただしこれは prompt-gen 都合で先に入れた provisional API なので、`lht-cmn` チーム側では trailing action 全般を扱える正式な契約として見直したい + - 正式方針が固まったら、今回の `clearable` 実装や CSS 調整はレビューのうえ置き換えたい diff --git a/lht-cmn/LICENSE b/lht-cmn/LICENSE new file mode 100644 index 0000000..4bb44d2 --- /dev/null +++ b/lht-cmn/LICENSE @@ -0,0 +1,197 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with the Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/lht-cmn/NOTICE b/lht-cmn/NOTICE new file mode 100644 index 0000000..d1b7fb9 --- /dev/null +++ b/lht-cmn/NOTICE @@ -0,0 +1,11 @@ +Copyright 2026 Toshiki Iga + +This product includes software developed by Toshiki Iga. + +Design direction: +- 本プロジェクトは Material Design 3 の設計原則を参照しています。 + +Third-party component implementation: +- `lht-cmn` の内部実装では、必要に応じて Material Web（`@material/web`）を優先利用します。 +- Material Web のライセンスは Apache License, Version 2.0 です。 +- Source: https://github.com/material-components/material-web diff --git a/lht-cmn/README.md b/lht-cmn/README.md new file mode 100644 index 0000000..e7dad3c --- /dev/null +++ b/lht-cmn/README.md @@ -0,0 +1,408 @@ +# lht-cmn + +`lht-cmn` は `local-html-tools` 全体で共有する UI コンポーネント基盤です。 + +- Version: `v20260308` +- License: Apache License 2.0 (`lht-cmn/LICENSE`) +- Copyright: Toshiki Iga + +## ライセンスと帰属 + +- `lht-cmn` 自体は Apache License 2.0 で配布します。 +- デザイン方針は Material Design 3 の設計原則を参照します。 +- 実装技術として、`lht-cmn` は必要に応じて Material Web（`@material/web`）を優先利用します。 +- Material Web のライセンスは Apache License 2.0 です。 +- 帰属情報の詳細は `lht-cmn/NOTICE` に記載します。 + +## 目的 + +`local-html-tools` では、入力・選択・ヘルプ・コピー・メニューなどの UI を複数ページで繰り返し実装してきました。 +`lht-cmn` はこの重複を減らし、UI を `lht-*` Web Components として共通化するためのレイヤーです。 + +## 基本方針 + +- デザイン基準は Material Design 3 +- 画面側の公開 UI レイヤーは常に `lht-*` とし、`md-*` を直接使わせない +- `lht-*` は self-contained を原則とし、アプリ側へ `md-*` の登録責務を漏らさない +- 実現手段として Material Web を優先利用してよい +- ただし Material 利用の有無に関わらず、`lht-*` は最低保証で壊れないことを優先する +- 内部実装として許可する型は次の 2 つに限定する: + - `md-*` 優先 + fallback + - 完全自前実装 +- 「Material 依存で fallback なし」は原則避け、採る場合は README に明示する +- fallback は Material の完全再現ではなく、公開 API の最低保証に留める + +## メリット + +- 画面ごとの重複実装を削減できる +- 見た目と挙動（必須表示、ヘルプ表示、フォーカス時の挙動）を統一できる +- 変更点を `lht-cmn` に集約でき、保守・レビューがしやすくなる +- 単一HTML生成前提でも、開発時の部品再利用性を維持できる +- 変更点が局所化され、生成AIが誤って別画面を壊す確率が下がる +- UI規約が `lht-*` に集約され、提案が毎回同じ型で出せる +- レビュー時に「画面の見た目差分」より「共通部品の差分」を見ればよくなり、判断が速くなる + +## 運用方針（重要） + +- 画面側（`docs/*-src.html`）は `lht-*` を利用し、`md-*` 直接実装の追加は原則避ける +- `lht-cmn/js/components.js` を共通コンポーネントの正本とする +- `lht-cmn/css/components.css` を実運用スタイルの正本とする +- `lht-cmn/` 配下（特に `js/components.js` / `css/components.css`）の変更は、必ずユーザーの明示許可を得てから実施する +- `md3/` は段階的にリファレンス用途へ縮退し、実運用スタイルは `lht-cmn` に集約する + +## 構成 + +- `lht-cmn/js/components.js` + - 共通 Web Components 定義 +- `lht-cmn/css/components.css` + - 上記コンポーネントの共通スタイル +- `lht-cmn/catalog/index.html` + - 実表示と HTML 利用例を並べて確認するコンポーネントカタログ + +### コンポーネント一覧 + +| コンポーネント | できること | 内部構造（概要） | +|---|---|---| +| `lht-help-tooltip` | `(i)` ヘルプアイコンとツールチップを1タグで配置できる | `md-icon-button` が使える環境ではそれを利用し、未定義時はネイティブ `button` fallback を生成。タグ内HTMLをツールチップ本文へ差し込む | +| `lht-text-field-help` | ラベル付き入力（単一行/複数行）とフォーカス時ヘルプ表示を共通化できる | `md-outlined-text-field` が使える環境ではそれを利用し、未定義時はネイティブ `input` / `textarea` fallback を生成。属性（`field-id`/`label`/`type`/`rows` など）を透過する | +| `lht-select-help` | ラベル付きドロップダウンとヘルプ表示を共通化できる | 内部で `md-outlined-select` を生成し、`` を使用する +3. `lht-select-help` で `