@ywal123456/jskim 0.5.0 → 0.5.2

package/docs/user-guide/08-nunjucks.md

@@ -0,0 +1,300 @@
+# Nunjucksの使い方
+
+この章では、JSKim の静的ページ制作で実用的な Nunjucks 文法を説明します。  
+Nunjucks 全体の公式 reference を置き換えるものではありません。
+
+## JSKim と Nunjucks
+
+| 役割 | 内容 |
+| ---- | ---- |
+| Nunjucks | template の記法と render engine |
+| JSKim | project / 設定 / files / build / watch / serve / dev をまとめる実行環境 |
+
+`{% ... %}` と `{{ ... }}` は Nunjucks の文法です。  
+一方、`rootPath` は Nunjucks 固有の変数ではなく、JSKim が render context に注入する予約値です。
+
+Nunjucks の機能すべてが JSKim 独自機能というわけではありません。  
+この章は、公式 sample で使われている範囲を中心にします。
+
+## Template inheritance
+
+各ページは共通 layout を継承します。
+
+```nunjucks
+{% extends "layouts/base.njk" %}
+```
+
+パスは、page file からの相対パスではありません。  
+Nunjucks loader が探す template root（`sourceDir` と `templates[]`）基準です。
+
+layout 自体は template root のため、直接 HTML としては output されません。  
+詳細は [files pipeline](07-files-pipeline.md) を参照してください。
+
+- layout: [`base.njk`](../../src/sample/layouts/base.njk)
+- 例: [Portal](../../src/sample/pages/index.html.njk)、[Dashboard](../../src/sample/pages/dashboard/index.html.njk)
+
+## block
+
+[`base.njk`](../../src/sample/layouts/base.njk) が定義する block は次の 3 つです。
+
+| block | 用途 |
+| ----- | ---- |
+| `title` | `<title>` の内容 |
+| `pageCss` | 画面群ごとの stylesheet など |
+| `content` | 本文 |
+
+Wizard 入力ページの例:
+
+```nunjucks
+{% block title %}情報入力 - {{ site.name }}{% endblock %}
+
+{% block pageCss %}
+  <link rel="stylesheet" href="assets/css/wizard.css">
+{% endblock %}
+
+{% block content %}
+  ...
+{% endblock %}
+```
+
+公式 sample に存在しない `script` block などはここでは扱いません。
+
+## include
+
+layout は共通 fragment を `include` します。
+
+```nunjucks
+{% include "components/header.njk" %}
+{% include "components/sidebar.njk" %}
+{% include "components/footer.njk" %}
+```
+
+breadcrumb は `breadcrumbs` があるときだけ読み込みます。
+
+```nunjucks
+{% if breadcrumbs %}
+  {% include "components/breadcrumb.njk" %}
+{% endif %}
+```
+
+Wizard ページでは手順表示も include します。
+
+```nunjucks
+{% include "components/wizard-steps.njk" %}
+```
+
+include 対象も独立 HTML としては output されません。
+
+- [`header.njk`](../../src/sample/components/header.njk)
+- [`wizard-steps.njk`](../../src/sample/components/wizard-steps.njk)
+- 例: [Wizard 入力](../../src/sample/pages/wizard/input.html.njk)
+
+## Variable output
+
+config の `data` や page 内の値を出力します。
+
+```nunjucks
+{{ site.name }}
+```
+
+JSKim の Nunjucks 環境は `autoescape: true` です。  
+HTML 特殊文字は既定で escape されます。
+
+信頼できない入力を raw HTML として埋め込む例は、このガイドでは扱いません。
+
+## set
+
+page 内の静的な値を定義します。
+
+```nunjucks
+{% set currentSection = "dashboard" %}
+{% set currentStep = 1 %}
+```
+
+CRUD 一覧では、表示用の配列も page 内で定義しています。
+
+```nunjucks
+{% set products = [
+  { id: "P-001", name: "サンプル商品A", status: "公開" },
+  ...
+] %}
+```
+
+これは外部 API や mock server ではありません。  
+application の状態管理機能でもありません。静的 UI sample のための値です。
+
+例: [CRUD 一覧](../../src/sample/pages/crud/index.html.njk)
+
+## for
+
+繰り返し HTML を生成します。CRUD 一覧の抜粋:
+
+```nunjucks
+{% for product in products %}
+  <tr>
+    <td>{{ product.id }}</td>
+    <td>{{ product.name }}</td>
+    ...
+  </tr>
+{% endfor %}
+```
+
+空配列の特別処理など、sample にない高度な用法は省略します。
+
+## if / elif / else
+
+条件で class や表示文言を切り替えます。  
+CRUD の status 表示:
+
+```nunjucks
+{% if product.status == "公開" %}
+  <span class="badge badge--public">公開</span>
+{% elif product.status == "非公開" %}
+  <span class="badge badge--private">非公開</span>
+{% else %}
+  <span class="badge badge--draft">下書き</span>
+{% endif %}
+```
+
+色だけで区別せず、テキストも残しています。
+
+Wizard の手順表示でも `currentStep` を比較します。
+
+```nunjucks
+{% if currentStep == 1 %} is-current{% elif currentStep > 1 %} is-complete{% endif %}
+```
+
+例: [`wizard-steps.njk`](../../src/sample/components/wizard-steps.njk)
+
+## default
+
+公式 sample では `default` filter を使っていません。  
+Nunjucks 自体の機能として存在しますが、このガイドの代表例には含めません。
+
+## Escaping
+
+JSKim は環境作成時に次を固定しています。
+
+- `autoescape: true`
+- `noCache: true`
+
+ユーザーが `jskim.config.js` の `nunjucks` で `autoescape` を切り替える設定はありません。  
+`nunjucks` 配下で設定できるのは主に `filters` と `globals` です。
+
+> **Warning**
+>
+> 信頼できる HTML だけを意図的に escape 解除したい場合は、  
+> filter 側で Nunjucks の `SafeString` を返す方法があります（公式 config の `toJson` 例）。  
+> 不特定の入力に対して安易に escape を外さないでください。
+
+XSS 対策の包括ガイドは、この章の範囲外です。
+
+## rootPath
+
+`rootPath` は Nunjucks 固有の組み込み変数ではありません。  
+JSKim が各ページの output 位置に応じて注入する予約 context です。
+
+| output | `rootPath` |
+| ------ | ---------- |
+| `index.html` | `./` |
+| `dashboard/index.html` | `../` |
+| `crud/detail.html` | `../` |
+
+共通 asset の例:
+
+```nunjucks
+{{ rootPath }}assets/css/common.css
+```
+
+> **Warning**
+>
+> page-local asset には `rootPath` を付けないでください。  
+> 詳細と正しい例は [files pipeline](07-files-pipeline.md) を参照してください。
+
+`data.rootPath` を設定すると予約語衝突エラーになります。
+
+## Config data
+
+`jskim.config.js` の `data` は、すべての render page の context に渡されます。
+
+```js
+data: {
+  site: {
+    name: 'JSKim UI Sample',
+    language: 'ja',
+    themeColor: '#222222',
+  },
+}
+```
+
+`{{ site.name }}` のように nested object を参照できます。
+
+| 種類 | 違い |
+| ---- | ---- |
+| `data` | project 全体で共通。config に書く |
+| `{% set %}` | その page（または template）内の局所値 |
+
+設定の詳細は [設定](06-configuration.md) を参照してください。
+
+## filters と globals
+
+登録場所:
+
+```js
+nunjucks: {
+  filters: { ... },
+  globals: { ... },
+}
+```
+
+- filter は **function** である必要があります
+- global は function または通常の値を登録できます
+- 非同期 function はサポートしていません
+
+公式 config にはデモ用の `formatPrice` / `toJson` / `currentYear` があります。  
+ただし公式 UI sample のページ本文は、これらに依存していません。  
+starter project の理解に必須ではありません。
+
+## nunjucks 設定でできること
+
+現在の schema でユーザーが書く主な key:
+
+| path | 内容 |
+| ---- | ---- |
+| `nunjucks.filters` | カスタム filter |
+| `nunjucks.globals` | カスタム global |
+
+JSKim が環境作成時に固定する値:
+
+| option | 値 |
+| ------ | -- |
+| `autoescape` | `true` |
+| `noCache` | `true`（loader / Environment） |
+
+Nunjucks upstream のすべての Environment option が、そのまま config から指定できるわけではありません。
+
+## 公式 sample の文法 mapping
+
+| 文法 | sample file | 用途 |
+| ---- | ----------- | ---- |
+| `extends` | [`pages/index.html.njk`](../../src/sample/pages/index.html.njk) など | 共通 layout 継承 |
+| `block` | [`layouts/base.njk`](../../src/sample/layouts/base.njk) | `title` / `pageCss` / `content` |
+| `include` | [`layouts/base.njk`](../../src/sample/layouts/base.njk) | header / sidebar / footer など |
+| `set` | [`pages/crud/index.html.njk`](../../src/sample/pages/crud/index.html.njk) | 静的データ・現在セクション |
+| `for` | [`pages/crud/index.html.njk`](../../src/sample/pages/crud/index.html.njk) | 一覧行の繰り返し |
+| `if` | [`pages/crud/index.html.njk`](../../src/sample/pages/crud/index.html.njk) | status badge 分岐 |
+| `include` + `if` | [`components/wizard-steps.njk`](../../src/sample/components/wizard-steps.njk) | Wizard 手順表示 |
+
+## この章で扱わない範囲
+
+次は公式 sample の範囲外、または別途の高度なトピックです。
+
+- macro
+- 非同期 filter
+- custom extension
+- Nunjucks JavaScript API 全体
+- backend での動的 template 実行
+- ブラウザが Nunjucks を実行する方式（build 時に HTML へ展開されます）
+
+開発中のエラー表示や reload は [開発機能](09-development-features.md)、  
+エラー対処は [エラーとトラブルシュート](10-errors-and-troubleshooting.md) を参照してください。

package/docs/user-guide/09-development-features.md

@@ -0,0 +1,228 @@
+# 開発機能
+
+この章では、主に `dev` 実行中の開発支援機能を説明します。  
+コマンドの選び方は [基本的な開発workflow](04-basic-workflow.md) も参照してください。
+
+## dev の構成
+
+`dev` は次の順で起動します。
+
+```text
+config を読み project を解決
+        ↓
+config 監視を開始
+        ↓
+live reload を準備
+        ↓
+静的サーバーを準備
+        ↓
+初回 build
+        ↓
+静的サーバーを listen
+        ↓
+source 監視を開始
+        ↓
+（--open 指定時）ブラウザを開く
+```
+
+| command | build | 監視 | サーバー | live reload |
+| ------- | ----- | ---- | -------- | ----------- |
+| `watch` | する | する | しない | しない |
+| `serve` | しない | しない | する | しない |
+| `dev` | する | する | する | する（既定） |
+
+`dev.liveReload` を `false` にすると、live reload 注入と SSE は無効になります。
+
+## Live reload
+
+`dev` かつ `liveReload: true` のとき、ブラウザは開発サーバーと接続します。
+
+- HTML レスポンスにだけクライアント script が注入されます（`dist` には書き込みません）
+- source 変更後の再 build 成功に応じて、ブラウザへ通知します
+- 接続が切れた場合、クライアントは再接続を試みます
+
+すべての変更が page 全体の reload になるわけではありません。  
+CSS の一部は soft reload になります。
+
+内部エンドポイントは `/_jskim/live-reload` です。  
+`serve` や `liveReload: false` では利用できません。
+
+## Full reload
+
+次のような変更では、通常 page 全体を再読み込みします。
+
+- HTML / Nunjucks（`.html.njk` など）の変更
+- 画像や JS などの非 CSS 変更
+- layout / component（`templates[]` 配下）の変更
+- CSS でも `add` / `unlink` など `change` 以外のイベント
+- CSS soft reload が失敗したときの fallback
+- config の再読み込み後に成功した再 build（概要）
+
+## CSS soft reload
+
+条件を満たすとき、page 全体を再読み込みせず、stylesheet だけを差し替えます。
+
+```text
+CSS soft reload
+→ 現在の page を保ったまま stylesheet を読み直す
+
+Full reload
+→ page 全体を読み直す
+```
+
+### 対象になる条件
+
+再 build 成功時の変更イベントが **すべて** 次を満たす場合です。
+
+- イベント種別が `change`
+- 対象パスの末尾が `.css` または `.css.njk`（大文字小文字を区別しない）
+- `templates[]` 配下ではない
+
+公式 sample の page-local CSS（平文 `.css`）も対象になり得ます。
+
+### ブラウザ側の制限
+
+クライアントは次だけを更新します。
+
+- `<link rel="stylesheet">`（`rel` に `stylesheet` を含むもの）
+- **same-origin** の URL
+
+次は soft reload の対象外です。
+
+- 外部 CDN の stylesheet
+- `<style>` の inline CSS
+- 動的に後から挿入した stylesheet（保証なし）
+- same-origin の stylesheet link が 1 つもない場合 → full reload
+
+読み込み失敗やタイムアウト時も full reload にフォールバックします。
+
+> **Note**
+>
+> form 入力内容やスクロール位置などの「状態保持」を、  
+> あらゆるケースで保証するものではありません。
+
+## Browser error overlay
+
+template / config / build のエラーを、開発中のブラウザ上に表示できます。
+
+主な特徴:
+
+- 現在表示中の page の上に重ねて表示
+- Shadow DOM を使い、page の CSS から隔離
+- メッセージはテキストとして表示（タイトルは `JSKim dev error`）
+- `Close` ボタンで一時的に閉じられる
+- エラーが解消され、成功通知を受けると自動で消える
+
+stack trace 全体をそのまま出す UI ではありません。  
+サーバーが送るメッセージ本文が中心です。
+
+## Last error replay
+
+ブラウザがエラー発生後に接続した場合や、再接続した直後でも、  
+まだエラー状態が残っていれば、サーバーが最後のエラーを再送します。
+
+複数のブラウザクライアントが接続している場合、同じ通知を受け取れます。
+
+## Recovery
+
+エラーを直して再 build が成功すると、おおむね次の流れになります。
+
+1. サーバー側のエラー状態が解除される
+2. overlay が消える（`clear-error`）
+3. 変更種別に応じて full reload または CSS soft reload
+
+config エラー中は、source 側の成功だけでは overlay を消さない優先順位があります。  
+config を直して有効な設定に戻す必要があります。
+
+process 自体は、個別の再 build 失敗だけでは終了しません。
+
+## Config hot reload
+
+| command | `jskim.config.js` を監視するか |
+| ------- | ------------------------------ |
+| `build` | しない |
+| `serve` | しない |
+| `watch` | する |
+| `dev` | する |
+
+読み込みや検証に失敗した場合:
+
+- 直前まで有効だった設定（last-known-good）を継続
+- terminal にエラーを表示
+- `dev` では browser overlay にも表示できる
+
+一時的に設定ファイルが消えた場合も、以前の正常な設定を継続します。
+
+成功して再読み込みできた場合は、監視対象を更新し、再 build します。
+
+## Restart-required 設定
+
+`dev` では、次の値が変わると **process の再起動が必要** です。
+
+- `outputDir`
+- `serve.host`
+- `serve.port`
+- `dev.liveReload`
+
+この場合、warning を出し、以前の正常な設定を継続します。  
+process を自動終了はしません。手動で `dev` を再起動してください。
+
+それ以外の多くの設定は、hot reload で反映を試みます。
+
+## CLI override の維持
+
+例:
+
+```bash
+jskim dev sample --host 127.0.0.1 --port 4000 --open
+```
+
+- `--host` / `--port` は config hot reload 後も CLI 指定が優先されます
+- `--open` は起動時に **1 回だけ** ブラウザを開きます（reload のたびに開き直しません）
+
+## Browser open
+
+`dev --open` は、サーバーの listen 成功後に OS の既定ブラウザで URL を開きます。
+
+失敗した場合:
+
+- warning を出す
+- 開発サーバー自体は継続する
+
+手動で次の URL を開けば確認できます（既定時）。
+
+```text
+http://127.0.0.1:3000/
+```
+
+> **Note**
+>
+> `serve` に `--open` はありません。
+
+## Strict CSP について
+
+JSKim は live reload 用 script を HTML レスポンスへ注入します。  
+overlay は Shadow DOM を使います。
+
+Strict な Content-Security-Policy 環境で、注入 script や接続が制限される可能性はあります。  
+ただし、現時点の公式 test で CSP ごとの動作を保証してはいません。
+
+## 開発機能の選び方
+
+| 必要 | 使い方 |
+| ---- | ------ |
+| output だけ継続更新 | `watch` |
+| 既存 `dist` をブラウザで確認 | `serve` |
+| reload 込みの統合開発 | `dev` |
+| 起動時にブラウザを開く | `dev --open` |
+| CSS 変更時に page 全体 reload を減らす | `dev`（条件付き soft reload） |
+
+## この章に関連する制限
+
+- JavaScript HMR ではありません
+- JS module の実行状態保持は保証しません
+- external / inline stylesheet は soft reload 対象外です
+- browser / OS 環境に依存する部分があります（`--open` など）
+
+全体の製品制限事項は [制限事項](14-limitations.md) を参照してください。  
+エラー別の対処は [エラーとトラブルシュート](10-errors-and-troubleshooting.md) を参照してください。