@ywal123456/jskim 0.5.0 → 0.5.2

package/docs/user-guide/12-crud-example.md

@@ -0,0 +1,203 @@
+# CRUD例
+
+この章では、公式 CRUD sample（商品管理の 6 画面）の構造と、静的な画面間 navigation を説明します。
+
+> **Warning**
+>
+> これは静的 UI sample です。  
+> JSKim が実際の登録・更新・削除機能を提供するわけではありません。
+
+> **Note**
+>
+> 以下のコードは核心部分だけの抜粋です。  
+> 全体の source は各 link から確認できます。
+
+## Sample の目的
+
+- 一覧 / 詳細 / 登録 / 編集 / 削除確認 / 完了という一般的な画面構成を示す
+- page 単位の静的 HTML として確認できる
+- 実際の登録・修正・削除は行わない
+- 入力値の保存や画面間引き渡しはない
+
+代表 source:
+
+- [商品一覧](../../src/sample/pages/crud/index.html.njk)
+
+## 関連 file
+
+```text
+pages/crud/
+├─ index.html.njk
+├─ detail.html.njk
+├─ create.html.njk
+├─ edit.html.njk
+├─ delete.html.njk
+├─ complete.html.njk
+└─ assets/css/crud.css
+```
+
+各 page:
+
+- [一覧](../../src/sample/pages/crud/index.html.njk)
+- [詳細](../../src/sample/pages/crud/detail.html.njk)
+- [登録](../../src/sample/pages/crud/create.html.njk)
+- [編集](../../src/sample/pages/crud/edit.html.njk)
+- [削除確認](../../src/sample/pages/crud/delete.html.njk)
+- [完了](../../src/sample/pages/crud/complete.html.njk)
+
+共通 layout / component の詳細は [Dashboard例](11-dashboard-example.md) と [Nunjucksの使い方](08-nunjucks.md) を参照してください。
+
+## 画面の移動
+
+```text
+商品一覧
+├─ 商品詳細
+│  ├─ 商品編集 ──→ 処理完了
+│  └─ 商品削除確認 ──→ 処理完了
+└─ 商品登録 ──→ 処理完了
+
+処理完了
+├─ 商品一覧へ戻る
+└─ Portal へ戻る
+```
+
+主な戻り先:
+
+| 画面 | 戻るリンク |
+| ---- | ---------- |
+| 詳細 | 一覧 |
+| 登録 | 一覧 |
+| 編集 | 詳細 |
+| 削除確認 | 詳細（削除せずに戻る） |
+| 完了 | 一覧 / Portal |
+
+## 商品一覧
+
+template 内の `products` 配列を `for` で表示します。
+
+```nunjucks
+{% for product in products %}
+  <tr>
+    <td>{{ product.id }}</td>
+    <td><a href="detail.html">{{ product.name }}</a></td>
+    ...
+  </tr>
+{% endfor %}
+```
+
+- table に caption / `scope="col"` がある
+- 商品名と「詳細」はどちらも `detail.html` へ
+- 「商品を登録する」は `create.html` へ
+- status は `if` で badge を切替
+
+## 商品詳細
+
+単一の `product` object を page 内で定義し、表示します。
+
+```nunjucks
+{% set product = {
+  id: "P-001",
+  name: "サンプル商品A",
+  ...
+} %}
+```
+
+- URL パラメータに応じた動的な取得ではない
+- 編集 / 削除 / 一覧への navigation がある
+
+## 商品登録
+
+form の見た目だけを持つ画面です。
+
+| 項目 | 属性の例 |
+| ---- | -------- |
+| 商品ID / 商品名 / カテゴリ / 価格 | `readonly` の text input |
+| ステータス | `disabled` の select |
+| 商品説明 | `readonly` の textarea |
+
+- 実際の submit はない
+- 「登録する」は `complete.html` への静的リンク
+- validation も入力保存もない
+
+## 商品編集
+
+登録画面に近い構成で、静的な初期値が入っています。
+
+- 詳細画面の固定商品を編集する体裁
+- 「更新する」も `complete.html` への静的リンク
+- 実際の更新処理はない
+
+> **Note**
+>
+> 登録と編集で form を macro / include にまとめていません。  
+> 静的 UI sample として、画面ごとの構成を追いやすくするためです。
+
+## 商品削除確認
+
+削除対象の静的情報と注意文を示します。
+
+- heading / 本文で「削除は実行されない」ことを明示
+- 「削除する」は色付きボタンだが、実際の削除は行わず `complete.html` へ移動
+
+## 処理完了
+
+登録・更新・削除の流れから共通で使う静的な完了 page です。
+
+- どの操作が成功したかを判定しない
+- 一覧または Portal へ戻れる
+
+## Nunjucks 文法 mapping
+
+| 文法 | file | 用途 |
+| ---- | ---- | ---- |
+| `set` array | `index.html.njk` | 商品一覧 |
+| `for` | `index.html.njk` | table row |
+| `if` | `index.html.njk` | status badge |
+| `set` object | `detail.html.njk` など | 静的な商品 |
+| variable output | 複数 page | 商品情報の表示 |
+
+基礎文法は [Nunjucksの使い方](08-nunjucks.md) を参照してください。
+
+## CRUD CSS
+
+| 項目 | パス |
+| ---- | ---- |
+| source | [`pages/crud/assets/css/crud.css`](../../src/sample/pages/crud/assets/css/crud.css) |
+| output | `dist/sample/crud/assets/css/crud.css` |
+| HTML | `assets/css/crud.css` |
+
+共通の見た目は `common.css`、CRUD 画面群の差分は `crud.css` が担当します。
+
+## 新しい CRUD 画面への拡張
+
+例:
+
+- 一覧の column を増やす
+- 詳細の項目を増やす
+- 確認 page を分ける
+- 完了 page を操作ごとに分ける
+- CRUD 専用 CSS を拡張する
+
+実際の backend 連携は JSKim の外（application 側）の作業です。
+
+## Backend とつなぐ場合
+
+概念だけ示します。
+
+- JSKim の build 結果は静的ファイル
+- API を呼ぶ JavaScript は利用者が別途書く
+- server-side でデータを注入する framework ではない
+- database / 認証 / 認可も JSKim の範囲外
+
+特定の backend framework の実装例は、このガイドでは扱いません。
+
+## Sample の限界
+
+- 実際の CRUD 処理はない
+- form submit はない
+- validation はない
+- persistence はない
+- URL パラメータ別の詳細表示はない
+- 外部 mock data file はない
+
+詳細は [制限事項](14-limitations.md) を参照してください。

package/docs/user-guide/13-wizard-example.md

@@ -0,0 +1,196 @@
+# Wizard例
+
+この章では、公式 Wizard sample（3 ステップ）と共通の step component を説明します。
+
+> **Warning**
+>
+> 入力内容の保存、画面間の引き継ぎ、送信処理はありません。  
+> 確認画面の値も入力画面から渡されたものではありません。
+
+> **Note**
+>
+> 以下のコードは核心部分だけの抜粋です。  
+> 全体の source は各 link から確認できます。
+
+## Sample の目的
+
+- 情報入力 → 入力内容確認 → 完了という段階型の画面構成を示す
+- layout / component / page-local CSS の使い方を確認する
+- 実際の入力値の受け渡しや保存はしない
+
+代表 source:
+
+- [情報入力](../../src/sample/pages/wizard/input.html.njk)
+
+## 関連 file
+
+```text
+components/wizard-steps.njk
+
+pages/wizard/
+├─ input.html.njk
+├─ confirm.html.njk
+├─ complete.html.njk
+└─ assets/css/wizard.css
+```
+
+- [`wizard-steps.njk`](../../src/sample/components/wizard-steps.njk)
+- [入力](../../src/sample/pages/wizard/input.html.njk)
+- [確認](../../src/sample/pages/wizard/confirm.html.njk)
+- [完了](../../src/sample/pages/wizard/complete.html.njk)
+
+共通 layout は [Dashboard例](11-dashboard-example.md) と同じです。
+
+## 画面の移動
+
+```text
+情報入力
+   ↓
+入力内容確認
+   ↓
+完了
+```
+
+戻り:
+
+```text
+入力内容確認 → 情報入力
+完了 → 情報入力 / Portal
+```
+
+「送信する」も完了画面への静的な移動です。
+
+## currentStep
+
+各 page が静的にステップ番号を持ちます。
+
+| page | 値 |
+| ---- | -- |
+| 情報入力 | `{% set currentStep = 1 %}` |
+| 入力内容確認 | `{% set currentStep = 2 %}` |
+| 完了 | `{% set currentStep = 3 %}` |
+
+- browser / session の application state ではない
+- `wizard-steps` component の表示切替のための値
+
+## wizard-steps component
+
+```nunjucks
+<li
+  class="wizard-steps__item{% if currentStep == 1 %} is-current{% elif currentStep > 1 %} is-complete{% endif %}"
+  {% if currentStep == 1 %}aria-current="step"{% endif %}
+>
+  <span class="wizard-steps__number">1</span>
+  <span class="wizard-steps__label">情報入力</span>
+  ...
+</li>
+```
+
+- ステップは 3 つ
+- 現在 / 完了 / 未実施を class とテキストで表現
+- 現在ステップには `aria-current="step"`
+- component 自体は直接 output されない
+
+## 情報入力
+
+見た目だけの入力欄です。
+
+| 項目 | name / 属性 |
+| ---- | ----------- |
+| 氏名 | `name` / `readonly` |
+| メールアドレス | `email` / `readonly` |
+| 電話番号 | `phone` / `readonly` |
+| お問い合わせ種別 | `category` / `disabled` select |
+| お問い合わせ内容 | `message` / `readonly` textarea |
+
+- 実際の submit はない
+- 「入力内容を確認する」は `confirm.html` へのリンク
+- 入力内容は保存されない
+
+## 入力内容確認
+
+template 内の固定 object を表示します。
+
+```nunjucks
+{% set application = {
+  name: "山田 太郎",
+  email: "taro@example.com",
+  phone: "090-0000-0000",
+  category: "商品について",
+  message: "sampleのお問い合わせ内容です。"
+} %}
+```
+
+> **Note**
+>
+> `taro@example.com` は予約された example domain の例です。  
+> 入力画面の内容が引き継がれた結果ではありません。
+
+- 「入力画面へ戻る」→ `input.html`
+- 「送信する」→ `complete.html`（実送信なし）
+
+## 完了
+
+静的な完了状態を示す画面です。
+
+- 入力の送信・保存は行われていないと明記
+- 「最初から確認する」→ `input.html`
+- Portal へも戻れる
+
+## Wizard CSS
+
+| 項目 | パス |
+| ---- | ---- |
+| source | [`pages/wizard/assets/css/wizard.css`](../../src/sample/pages/wizard/assets/css/wizard.css) |
+| output | `dist/sample/wizard/assets/css/wizard.css` |
+| HTML | `assets/css/wizard.css` |
+
+step indicator、form、確認リスト、完了パネルなどの見た目を担当します。  
+共通部分は `common.css` です。
+
+## アクセシビリティ
+
+実際の sample が備えるもの:
+
+- 手順は `<ol>`
+- 現在ステップに `aria-current="step"`
+- 各入力に `label`
+- 状態テキスト（現在 / 完了 / 未実施）
+- 色だけに頼らない状態表現
+
+これ以上のアクセシビリティ機能を、sample が保証するわけではありません。
+
+## ステップを増やす方法
+
+4 ステップにする場合の概念的な順序:
+
+1. 新しい page（`.html.njk`）を作る
+2. `wizard-steps.njk` に項目を足す
+3. 各 page の `currentStep` を調整する
+4. navigation の link を直す
+5. CSS を確認する
+6. `dev` / `build` で link を検査する
+
+自動 routing や共有 state の機能はありません。
+
+## 実際の Wizard にする場合
+
+JSKim の外で必要になる典型例:
+
+- 入力値の保存
+- validation
+- 画面間の state
+- submit / API / backend
+- 直接 URL アクセスの制御
+- 完了後の state クリア
+
+具体的な application 実装コードは、このガイドでは扱いません。
+
+## Sample の限界
+
+- 入力の引き継ぎはない
+- 送信・保存はない
+- step は page ごとの静的値
+- session / localStorage による状態管理はない
+
+製品全体の境界は [制限事項](14-limitations.md) を参照してください。

package/docs/user-guide/14-limitations.md

@@ -0,0 +1,186 @@
+# 制限事項
+
+この章では、JSKim が提供しないことと、その意味を整理します。  
+ツールの境界を理解し、別途何が必要かを判断するための章です。
+
+## 静的サイトの build 環境である
+
+**提供しないもの:** server-side runtime、SSR framework、SPA framework。
+
+**意味:** build 結果は静的な HTML / CSS / 画像などです。サーバー上で template を都度実行する製品ではありません。
+
+**必要な場合:** SSR や SPA が必要なら、その目的に合う別のツールを検討します。
+
+> **Note**
+>
+> JavaScript file 自体の render / copy は可能です。  
+> ただし JSKim は JavaScript bundler ではありません（後述）。
+
+## Backend 機能はない
+
+**提供しないもの:**
+
+- API server
+- database
+- 認証 / 認可
+- session
+- 業務ロジック
+- 実際の CRUD
+- Wizard の入力 state 管理
+
+**意味:** 公式 sample の CRUD / Wizard も画面構成の例です。
+
+**必要な場合:** backend とフロントエンド連携は、利用者が別途実装します。  
+画面例は [CRUD例](12-crud-example.md) / [Wizard例](13-wizard-example.md) を参照してください。
+
+## HTML の自動 import / migration はない
+
+**提供しないもの:** 既存 HTML の自動解析、分割、変換。
+
+**意味:** 既存サイトの移行は、利用者が project に合わせて手作業（または別ツール）で行います。  
+JSKim core の責任範囲ではありません。
+
+将来の提供をこのガイドで約束しません。
+
+## Bundler ではない
+
+**提供しないもの:**
+
+- JavaScript module bundling
+- npm 依存の解決を伴う bundle
+- transpile
+- minify
+- tree shaking
+- code splitting
+
+**意味:** `.js` / `.js.njk` は files pipeline で copy または Nunjucks render できますが、webpack / Vite のような変換パイプラインではありません。
+
+**必要な場合:** bundling が必要なら専用の bundler を併用します。
+
+## CSS preprocessor ではない
+
+**提供しないもの:** Sass / Less / PostCSS などの組み込み処理、autoprefix、CSS minify。
+
+**意味:** `.css.njk` は Nunjucks で文字列を生成するだけで、CSS compiler ではありません。平文 `.css` は byte copy です。
+
+**必要な場合:** preprocessor が必要なら、別工程で生成した CSS を JSKim の source に置く方法を検討します。
+
+## 独自の plugin システムはない
+
+**提供しないもの:** JSKim 専用の plugin / extension 機構。
+
+**意味:** 拡張の主な手段は `jskim.config.js` の `nunjucks.filters` / `nunjucks.globals` です。  
+これは Nunjucks への登録であり、汎用 plugin marketplace ではありません。
+
+## Build は依存グラフに基づく増分 build ではない
+
+**提供しないもの:** file 単位の依存解析による incremental build。
+
+**意味:** 変更検知後は、設定に従い clean（既定）付きの全体再 build が基本です。  
+大規模 project では、変更のたびに全体を作り直す前提で設計します。
+
+速度の優劣を数値で断定はしません。
+
+## Multi-project の command 制限
+
+| command | `--all` |
+| ------- | ------- |
+| `build` | 対応 |
+| `watch` | 非対応 |
+| `serve` | 非対応 |
+| `dev` | 非対応 |
+
+複数 project を同時に `watch` / `serve` / `dev` したい場合は、別 process で個別に起動する必要があります。
+
+## Port の扱い
+
+- 既定は `127.0.0.1:3000`
+- 衝突時に次の空き port を自動選択しない
+- `--port` または `serve.port` で変更する
+- process manager 機能はない
+
+詳細は [エラーとトラブルシュート](10-errors-and-troubleshooting.md) を参照してください。
+
+## Browser open
+
+- `dev --open` のみ
+- `serve --open` は非対応
+- OS の既定ブラウザ起動に依存
+- 失敗時は warning で、開発サーバーは継続
+
+## CSS soft reload の範囲
+
+対象になり得る条件（概要）:
+
+- `.css` / `.css.njk` の `change`
+- `templates[]` 配下ではない
+- same-origin の `<link rel="stylesheet">`
+
+対象外・制限の例:
+
+- external stylesheet
+- `<style>` inline
+- 動的挿入 stylesheet（保証なし）
+- soft reload 失敗時は full reload
+
+詳細は [開発機能](09-development-features.md) を参照してください。
+
+## Live reload は HMR ではない
+
+- page の full reload、または CSS の差し替え
+- JavaScript module の実行状態保持は保証しない
+- React / Vue などの HMR と同種の機能ではない
+
+## Browser overlay と環境依存
+
+- `dev` + live reload 時に HTML へ script を注入
+- overlay は Shadow DOM を使用
+
+Strict な Content-Security-Policy など、ブラウザや page のセキュリティ設定によっては、注入や接続が制限される可能性があります。  
+すべての CSP 設定での動作を保証するものでも、必ず失敗すると断定するものでもありません。
+
+## Config と Nunjucks の境界
+
+- 余分な config key は無視されることがある（厳密 schema ではない）
+- `autoescape` / `noCache` は JSKim が固定
+- `data.rootPath` は予約
+- `dev` では一部設定変更に process 再起動が必要
+
+Nunjucks 全体の機能を JSKim の契約として保証しません。  
+公式ガイドは sample で有用な文法が中心です（[Nunjucksの使い方](08-nunjucks.md)）。
+
+## Output directory
+
+- `dist` は source ではない
+- `build.clean` が `true`（既定）なら build 前に削除される
+- `false` の場合、消えた source に対応する古い output が残ることがある
+- 手編集の維持は保証しない
+
+## Platform / path
+
+- Windows では大文字小文字違いの output 衝突を検出する
+- path は Node の `path` で扱い、HTML 内は `/` を使う
+- Windows / macOS / Linux を特別に排除していない
+- `--open` の挙動は OS の handler に依存する
+
+## 公式 sample の範囲
+
+- 学習用の静的 UI sample
+- production-ready な application template ではない
+- デザインシステム / UI ライブラリではない
+- セキュリティや業務要件を満たすことを保証しない
+
+## ツール選択の目安
+
+| 必要 | 判断 |
+| ---- | ---- |
+| Nunjucks で静的 page を生成したい | JSKim が適合しやすい |
+| API / database server | 別途 backend が必要 |
+| JS bundling / transpile | 別途 bundler が必要 |
+| 既存 HTML の自動 migration | 別作業 / 別ツールが必要 |
+| 本格的な SPA | 目的に合う application framework を検討 |
+
+特定製品の推奨や比較評価は、この章の範囲外です。
+
+関連する運用上の確認は [エラーとトラブルシュート](10-errors-and-troubleshooting.md)、  
+画面例は [Dashboard例](11-dashboard-example.md) 以降を参照してください。

package/docs/user-guide/README.md

@@ -0,0 +1,99 @@
+# JSKim ユーザーガイド
+
+このドキュメントは、JSKim を初めて利用する方向けの公式ガイドです。
+
+対象 version は **v0.5.2** です。説明は現在の実装と公式 sample source に基づきます。
+
+## このガイドについて
+
+主な読者は次のとおりです。
+
+> HTML、CSS、JavaScript の基本的な知識はあるが、  
+> JSKim および Nunjucks を初めて利用するユーザー
+
+このガイドでは、次のことを学べます。
+
+- JSKim が何をするツールか
+- project の作り方と build / 開発サーバーの動かし方
+- 公式 sample の構成と Dashboard / CRUD / Wizard の読み方
+- CLI、設定、files pipeline、Nunjucks の使い方
+- 開発機能と代表的なエラーの対処
+- JSKim の適用範囲と制限
+
+説明は公式の静的 UI sample（`src/sample/`）とあわせて読む前提です。  
+creator（`create-jskim`）で生成した project にも、同じ sample が含まれます。
+
+## 章一覧
+
+1. [JSKimとは](01-introduction.md)
+2. [はじめ方](02-getting-started.md)
+3. [プロジェクト構成](03-project-structure.md)
+4. [基本的な開発workflow](04-basic-workflow.md)
+5. [CLIリファレンス](05-cli-reference.md)
+6. [設定](06-configuration.md)
+7. [files pipeline](07-files-pipeline.md)
+8. [Nunjucksの使い方](08-nunjucks.md)
+9. [開発機能](09-development-features.md)
+10. [エラーとトラブルシュート](10-errors-and-troubleshooting.md)
+11. [Dashboard例](11-dashboard-example.md)
+12. [CRUD例](12-crud-example.md)
+13. [Wizard例](13-wizard-example.md)
+14. [制限事項](14-limitations.md)
+
+## 読み方
+
+### 初めて使う場合
+
+次の順がわかりやすいです。
+
+1. [JSKimとは](01-introduction.md)
+2. [はじめ方](02-getting-started.md)
+3. [プロジェクト構成](03-project-structure.md)
+4. [基本的な開発workflow](04-basic-workflow.md)
+5. 公式 sample を見ながら [Dashboard例](11-dashboard-example.md) 以降
+
+必要に応じて CLI / 設定 / files pipeline / Nunjucks の章を参照してください。
+
+### 必要なときだけ参照する場合
+
+| 知りたいこと | 章 |
+| ------------ | -- |
+| コマンドと option | [CLIリファレンス](05-cli-reference.md) |
+| `jskim.config.js` | [設定](06-configuration.md) |
+| render / copy / `rootPath` | [files pipeline](07-files-pipeline.md) |
+| template 文法 | [Nunjucksの使い方](08-nunjucks.md) |
+| live reload / overlay | [開発機能](09-development-features.md) |
+| エラー対処 | [エラーとトラブルシュート](10-errors-and-troubleshooting.md) |
+| できること / できないこと | [制限事項](14-limitations.md) |
+
+### 公式 sample とあわせて読む
+
+入口:
+
+- [Portal](../../src/sample/pages/index.html.njk)
+
+画面例:
+
+- [Dashboard例](11-dashboard-example.md)
+- [CRUD例](12-crud-example.md)
+- [Wizard例](13-wizard-example.md)
+
+## このガイドの範囲
+
+### JSKim が提供するもの
+
+- Nunjucks に基づく静的 HTML の render
+- CSS や画像などの asset copy
+- `build` / `watch` / `serve` / `dev` の workflow
+- 開発サーバーと、開発中の reload / エラー表示の支援
+
+### JSKim が提供しないもの
+
+- backend
+- API
+- database
+- 実際の CRUD 処理
+- 実際の Wizard state 管理
+- 既存 HTML の自動取り込みや移行ツール
+
+詳細は [制限事項](14-limitations.md) を参照してください。