@ywal123456/jskim 0.5.1 → 0.5.2

package/README.md

@@ -47,6 +47,9 @@ Nunjucks を使った汎用の静的 HTML ビルド環境です。
 
 詳細:
 
+- 公式ユーザーガイド: [docs/user-guide/README.md](docs/user-guide/README.md)
+- 公式ユーザーガイド PDF（npm package 同梱）: `node_modules/@ywal123456/jskim/docs/JSKim_User_Guide_v0.5.2.pdf`
+- PDF生成手順: [docs/user-guide-pdf-build.md](docs/user-guide-pdf-build.md)（maintainer 向け。release 用 PDF は `npm run docs:pdf:package`）
 - [docs/configuration.md](docs/configuration.md)
 - [docs/create-jskim.md](docs/create-jskim.md)
 - [docs/publishing.md](docs/publishing.md)（maintainer 向け release 手順）
@@ -136,16 +139,18 @@ module.exports = {
 例:
 
 ```text
-src/sample/pages/index.html.njk        → dist/sample/index.html
-src/sample/pages/assets/css/style.css.njk → dist/sample/assets/css/style.css
-src/sample/pages/assets/image/logo.svg → dist/sample/assets/image/logo.svg
+src/sample/pages/index.html.njk                 → dist/sample/index.html
+src/sample/pages/dashboard/index.html.njk       → dist/sample/dashboard/index.html
+src/sample/pages/assets/css/common.css          → dist/sample/assets/css/common.css
+src/sample/pages/dashboard/assets/css/dashboard.css → dist/sample/dashboard/assets/css/dashboard.css
+src/sample/pages/assets/img/logo.svg            → dist/sample/assets/img/logo.svg
 ```
 
 推奨命名:
 
-- HTML は `index.html.njk`、`request/index.html.njk` のように最終拡張子を含める
+- HTML は `index.html.njk`、`dashboard/index.html.njk` のように最終拡張子を含める
 - CSS / JS を Nunjucks で処理する場合は `style.css.njk`、`main.js.njk` のように書く
-- 画像などテンプレート処理しないファイルは通常の拡張子のまま置く
+- 画像や平文 CSS などテンプレート処理しないファイルは通常の拡張子のまま置く
 
 `templates` に指定した `layouts` / `components` は loader の検索パスになり、直接出力されません。
 
@@ -269,8 +274,8 @@ jskim/
 │  └─ sample/
 │     ├─ pages/
 │     │  ├─ index.html.njk
-│     │  ├─ assets/
-│     │  └─ request/
+│     │  ├─ dashboard/
+│     │  └─ assets/
 │     ├─ layouts/
 │     └─ components/
 └─ dist/
@@ -282,21 +287,27 @@ jskim/
 各 `.njk` ファイルの最終出力位置を基準に `rootPath` が自動計算され、Nunjucks context に注入されます。
 
 ```njk
-<link rel="stylesheet" href="{{ rootPath }}assets/css/style.css">
-<a href="{{ rootPath }}index.html">Home</a>
+<link rel="stylesheet" href="{{ rootPath }}assets/css/common.css">
+<a href="{{ rootPath }}index.html">Portal</a>
+```
+
+ページローカル asset は出力ページからの相対パスで参照します。
+
+```njk
+<link rel="stylesheet" href="assets/css/dashboard.css">
 ```
 
 | 出力ファイル | rootPath |
 |-----------|----------|
 | `dist/sample/index.html` | `./` |
-| `dist/sample/request/index.html` | `../` |
+| `dist/sample/dashboard/index.html` | `../` |
 | `dist/sample/guide/syntax/index.html` | `../../` |
 
 `data.rootPath` は予約語のため使えません。
 
 ## sample
 
-`src/sample` は files pipeline、`data`、custom filter、global、ページ別 assets を示す小さなサンプルです。
+`src/sample` は公式の静的 UI sample です。Portal / Dashboard / CRUD / Wizard を含みます。API や入力保存などの application 処理は含みません。`create-jskim` が生成する project にも同じ sample が入る。
 
 ```bash
 npm run build -- sample

package/docs/create-jskim.md

@@ -56,27 +56,42 @@ project/
    └─ sample/
       ├─ pages/
       │  ├─ index.html.njk
-      │  ├─ assets/
-      │  │  ├─ css/style.css.njk
-      │  │  ├─ js/main.js.njk
-      │  │  └─ image/logo.svg
-      │  └─ request/
-      │     ├─ index.html.njk
-      │     └─ assets/
+      │  ├─ dashboard/
+      │  │  ├─ index.html.njk
+      │  │  └─ assets/css/dashboard.css
+      │  ├─ crud/
+      │  │  ├─ index.html.njk
+      │  │  ├─ detail.html.njk
+      │  │  ├─ create.html.njk
+      │  │  ├─ edit.html.njk
+      │  │  ├─ delete.html.njk
+      │  │  ├─ complete.html.njk
+      │  │  └─ assets/css/crud.css
+      │  ├─ wizard/
+      │  │  ├─ input.html.njk
+      │  │  ├─ confirm.html.njk
+      │  │  ├─ complete.html.njk
+      │  │  └─ assets/css/wizard.css
+      │  └─ assets/
+      │     ├─ css/common.css
+      │     └─ img/logo.svg
       ├─ layouts/base.njk
       └─ components/
          ├─ header.njk
-         └─ footer.njk
+         ├─ sidebar.njk
+         ├─ breadcrumb.njk
+         ├─ footer.njk
+         └─ wizard-steps.njk
 ```
 
-`jskim.config.js` は `files: [{ from: 'pages', to: '' }]` を使います。`.njk` は末尾の `.njk` だけを外してレンダリングし、画像などはそのままコピーします。
+`jskim.config.js` は `files: [{ from: 'pages', to: '' }]` を使います。`.njk` は末尾の `.njk` だけを外してレンダリングし、平文 CSS / 画像などはそのままコピーします。公式 sample は静的 UI であり、application 処理は含みません。
 
-`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。既定の engine dependency は `@ywal123456/jskim`（`^0.5.1`）です。
+`package.json` の scripts は bin 名 `jskim` を使います（package name ではありません）。既定の engine dependency は `@ywal123456/jskim`（`^0.5.2`）です。
 
 ```json
 {
   "devDependencies": {
-    "@ywal123456/jskim": "^0.5.1"
+    "@ywal123456/jskim": "^0.5.2"
   },
   "scripts": {
     "build": "jskim build sample",
@@ -102,7 +117,7 @@ create package の `package.json` に `jskimEngine` metadata を持ち、生成
 {
   "jskimEngine": {
     "packageName": "@ywal123456/jskim",
-    "version": "^0.5.1"
+    "version": "^0.5.2"
   }
 }
 ```

package/docs/user-guide/01-introduction.md

@@ -0,0 +1,98 @@
+# JSKimとは
+
+この章では、JSKim がどのようなツールか、何を解決し、どのような用途に向くかを説明します。
+
+## JSKim の概要
+
+JSKim は、Nunjucks を使って静的 HTML を生成する開発環境です。
+
+source（`sourceDir`）を管理し、build によって output（`outputDir`）を生成します。layout や component を再利用でき、CSS や画像などの asset もまとめて扱えます。開発中は `watch` / `serve` / `dev` を使い、配布結果は通常の静的ファイルです。
+
+「framework」と呼ぶこともできますが、backend framework や SPA framework ではありません。テンプレートと静的ファイルを整理し、build 結果を作るためのツールです。
+
+## 解決しようとする問題
+
+静的な HTML サイトを手作業だけで増やすと、次のような問題が起きやすくなります。
+
+- 複数ページで header / footer などの共通部分が重複する
+- ページ数が増えると、共通箇所の修正漏れが起きやすい
+- 編集用の source と、配布用の output が混ざりやすい
+- 静的 asset のパス管理が煩雑になる
+- build / watch / 開発サーバーの手順が統一されない
+- template の誤りに気づくのが遅れる
+
+JSKim は、これらの作業を `jskim.config.js` を基準にした一連のコマンドとしてまとめます。
+
+## 基本的な処理の流れ
+
+推奨設定である files pipeline では、大まかに次の流れで処理します。
+
+```text
+src/sample/
+   │
+   ├─ pages/ 配下の *.njk ── render（末尾 .njk を外す）──┐
+   ├─ pages/ 配下の CSS / 画像 ── copy ──────────────────┤
+   └─ layouts / components ── template root（直接出力しない）│
+                                                           ▼
+                                                     dist/sample/
+```
+
+`layouts` や `components` は `extends` / `include` 用の template root です。それ自体は output されません。  
+詳細な規則は [files pipeline](07-files-pipeline.md) を参照してください。
+
+## JSKim に向いている project
+
+次のような project に向いています。
+
+- 複数の静的 HTML ページを持つ website
+- 共通 layout / component を使う project
+- build 結果を静的 hosting や既存サーバーへ配置する project
+- frontend bundler を使わず、HTML / CSS / JS asset を整理したい project
+
+## JSKim の範囲外
+
+次の用途は JSKim の範囲外です。
+
+- backend application framework ではない
+- database 機能はない
+- API server 機能はない
+- React / Vue のような SPA framework ではない
+- JavaScript bundler ではない
+- 既存 HTML の自動取り込みや移行ツールではない
+- 実際の CRUD / Wizard 業務ロジックは提供しない
+
+公式 sample の CRUD / Wizard は、画面構成を示す静的 UI sample です。保存や送信などの application 処理はありません。
+
+## JSKim と Nunjucks の関係
+
+役割を分けると次のとおりです。
+
+- **Nunjucks** — template の記法と render engine
+- **JSKim** — project / 設定 / files / build / watch / serve / dev をまとめる実行環境
+
+Nunjucks の文法すべてが JSKim 独自機能というわけではありません。  
+このユーザーガイドでは、JSKim の利用で実務的に必要な文法を中心に扱います。
+
+## 公式 sample の紹介
+
+公式 sample は次の画面グループで構成されています。
+
+| 画面グループ | 役割 |
+| ------------ | ---- |
+| Portal | sample 全体の入口。各画面グループへの導線をまとめる |
+| Dashboard | 共通 layout と静的データを使った管理画面の見た目例 |
+| CRUD | 一覧・詳細・登録・編集・削除確認などの画面構成例 |
+| Wizard | 入力・確認・完了の 3 ステップ画面構成例 |
+
+いずれも静的 UI です。API 通信や入力の永続化はありません。
+
+代表的な source:
+
+- [Portal](../../src/sample/pages/index.html.njk)
+- [Dashboard](../../src/sample/pages/dashboard/index.html.njk)
+- [CRUD](../../src/sample/pages/crud/index.html.njk)
+- [Wizard（入力）](../../src/sample/pages/wizard/input.html.njk)
+
+読み方は [Dashboard例](11-dashboard-example.md)、[CRUD例](12-crud-example.md)、[Wizard例](13-wizard-example.md) を参照してください。
+
+次の章では、project を作成して sample をブラウザで確認する手順を説明します。

package/docs/user-guide/02-getting-started.md

@@ -0,0 +1,162 @@
+# はじめ方
+
+この章では、JSKim の project を作成し、ブラウザで公式 sample を確認し、production build まで実行する手順を説明します。
+
+## 事前準備
+
+JSKim engine（`@ywal123456/jskim`）と creator（`create-jskim`）は、いずれも Node.js **18 以上**を想定しています（`package.json` の `engines.node` が `>=18`）。
+
+package manager は npm / pnpm / yarn を公式に案内しています。OS として Windows / macOS / Linux を特別に制限してはいません。パス処理は Node の `path` を使います。
+
+あらかじめ Node.js と、利用する package manager がコマンドとして認識できる状態にしてください。
+
+## Project の作成
+
+推奨の作成コマンドは次のとおりです。
+
+```bash
+npm create jskim@latest my-project
+```
+
+他の package manager の例:
+
+| package manager | 作成コマンド |
+| --------------- | ------------ |
+| npm | `npm create jskim@latest my-project` |
+| pnpm | `pnpm create jskim my-project` |
+| yarn | `yarn create jskim my-project` |
+
+代替として、次も利用できます。
+
+```bash
+npx create-jskim my-project
+```
+
+ディレクトリ名を省略すると、プロジェクト名を尋ねます。空のまま Enter すると既定値 `jskim-project` を使います。
+
+空ではない既存ディレクトリは上書きしません。
+
+## 生成結果
+
+生成直後の主要な構成は次のとおりです。
+
+```text
+my-project/
+├─ package.json
+├─ jskim.config.js
+├─ README.md
+├─ .gitignore
+└─ src/
+   └─ sample/
+      ├─ layouts/
+      ├─ components/
+      └─ pages/
+```
+
+`package.json` は creator が生成します。engine dependency は `@ywal123456/jskim`（`^0.5.2`）です。
+`src/sample/` には公式の静的 UI sample（Portal / Dashboard / CRUD / Wizard）が含まれます。
+
+## Dependency のインストール
+
+creator は **自動で install を実行しません**。また `git init` も実行しません。
+
+生成完了時の案内は、実行した package manager に合わせて install / 開発コマンドを表示します。検知できない場合は npm 向けの案内になることがあります。
+
+project ディレクトリへ移動してから、次を実行してください。
+
+```bash
+npm install
+```
+
+```bash
+pnpm install
+```
+
+```bash
+yarn install
+```
+
+## 開発サーバーの実行
+
+生成された `package.json` の `dev` script は `jskim dev sample` です。
+
+```bash
+npm run dev
+```
+
+package manager ごとの例:
+
+| package manager | 開発コマンド |
+| --------------- | ------------ |
+| npm | `npm run dev` |
+| pnpm | `pnpm dev` |
+| yarn | `yarn dev` |
+
+既定の開発サーバー URL は次です。
+
+```text
+http://127.0.0.1:3000/
+```
+
+ブラウザでは Portal が表示されます。sidebar やカードから Dashboard / CRUD / Wizard へ移動できます。
+
+source を保存すると再 build され、ブラウザへ反映されます。template などに誤りがあると、ブラウザ上の overlay に表示されることがあります。  
+詳細は [開発機能](09-development-features.md) を参照してください。
+
+## 最初の修正
+
+まずは Portal の説明文を変更してみます。
+
+編集する file:
+
+- [src/sample/pages/index.html.njk](../../src/sample/pages/index.html.njk)
+
+次の lead 文を探します。
+
+```nunjucks
+<p class="lead">
+  JSKim の files pipeline で画面構成、template 分割、asset 配置を確認できる
+  静的 UI sample です。
+</p>
+```
+
+文言を少し変えて保存し、ブラウザを確認してください。Portal の説明が更新されていれば、source から output への流れを確認できています。
+
+## Production build
+
+配布用の output を作るには次を実行します。
+
+```bash
+npm run build
+```
+
+生成 script は `jskim build sample` です。結果は次のディレクトリに出力されます。
+
+```text
+dist/sample/
+```
+
+ここには通常の HTML / CSS / SVG などの静的ファイルが並びます。  
+どこへ配置するかは hosting 環境によって異なるため、特定の提供元の手順はこのガイドでは扱いません。
+
+## 主なコマンドのまとめ
+
+| 目的 | 例（npm） |
+| ---- | --------- |
+| dependency のインストール | `npm install` |
+| 開発サーバー | `npm run dev` |
+| production output の生成 | `npm run build` |
+
+`watch`（監視して再 build）と `serve`（output の静的配信のみ）も生成 script に含まれます。  
+使い分けは [基本的な開発workflow](04-basic-workflow.md)、構文の詳細は [CLIリファレンス](05-cli-reference.md) を参照してください。
+
+## うまく動かないとき
+
+よくある原因は次のとおりです。
+
+- 既定 port（`3000`）が他のプロセスで使われている
+- install を実行していない
+- project ルート以外のディレクトリでコマンドを実行している
+- Node.js / package manager が PATH 上で認識されていない
+
+エラーメッセージごとの対処は [エラーとトラブルシュート](10-errors-and-troubleshooting.md) を参照してください。

package/docs/user-guide/03-project-structure.md

@@ -0,0 +1,216 @@
+# プロジェクト構成
+
+この章では、`create-jskim` が生成する project の directory 構成と、各要素の役割を説明します。
+
+## 全体構成
+
+生成直後のルート構成は次のとおりです。
+
+```text
+my-project/
+├─ jskim.config.js
+├─ package.json
+├─ README.md
+├─ .gitignore
+├─ src/
+│  └─ sample/
+└─ dist/          ← build 後に生成されることがある
+   └─ sample/
+```
+
+`dist/` は build を実行するまで存在しない場合があります。source は `src/sample/`、output は `dist/sample/` です。
+
+`src/sample/` の概要は次のとおりです。
+
+```text
+src/sample/
+├─ layouts/
+│  └─ base.njk
+├─ components/
+│  ├─ header.njk
+│  ├─ sidebar.njk
+│  ├─ breadcrumb.njk
+│  ├─ footer.njk
+│  └─ wizard-steps.njk
+└─ pages/
+   ├─ index.html.njk
+   ├─ assets/
+   │  ├─ css/common.css
+   │  └─ img/logo.svg
+   ├─ dashboard/
+   ├─ crud/
+   └─ wizard/
+```
+
+## jskim.config.js
+
+`jskim.config.js` は project の定義です。動作の基準はこのファイルにあります。
+
+公式 sample では、おおむね次の考え方で設定されています。
+
+- `sourceDir` — source のルート（例: `src/sample`）
+- `outputDir` — output のルート（例: `dist/sample`）
+- `files` — pages 配下をまとめて処理する pipeline（例: `{ from: 'pages', to: '' }`）
+- `templates` — `extends` / `include` 用の検索パス（例: `layouts`, `components`）
+- `data` — 全 template へ渡す共通データ（例: `site.name`）
+
+設定の一部（概念）:
+
+```js
+defaults: {
+  files: [{ from: 'pages', to: '' }],
+  templates: ['layouts', 'components'],
+  data: {
+    site: {
+      name: 'JSKim UI Sample',
+      language: 'ja',
+      themeColor: '#222222',
+    },
+  },
+}
+```
+
+オプションの詳細は [設定](06-configuration.md) を参照してください。
+
+## src/sample
+
+`src/sample/` は公式 sample の source root です。  
+この repository の sample と、creator が生成する sample は同じ構成です。
+
+主な役割:
+
+- `layouts/` — 文書全体の共通枠
+- `components/` — header など再利用部品
+- `pages/` — 実際に output されるページと asset
+
+## layouts
+
+共通 layout は次の file です。
+
+- [`base.njk`](../../src/sample/layouts/base.njk)
+
+HTML document の骨格（`title`、共通 CSS、header、sidebar、breadcrumb、footer）を定義します。  
+各ページは `{% extends "layouts/base.njk" %}` でこの layout を継承し、`{% block content %}` などに本文を書きます。
+
+`layouts` は template root のため、それ自体は output されません。
+
+## components
+
+components は次のとおりです。
+
+| file | 役割 |
+| ---- | ---- |
+| [`header.njk`](../../src/sample/components/header.njk) | 上部ヘッダーとブランド表示 |
+| [`sidebar.njk`](../../src/sample/components/sidebar.njk) | 画面グループへのナビ |
+| [`breadcrumb.njk`](../../src/sample/components/breadcrumb.njk) | パンくずリスト |
+| [`footer.njk`](../../src/sample/components/footer.njk) | フッター |
+| [`wizard-steps.njk`](../../src/sample/components/wizard-steps.njk) | Wizard の手順表示 |
+
+layout から `{% include "components/header.njk" %}` のように読み込みます。  
+components も template root のため、独立した HTML ページとしては output されません。
+
+## pages
+
+`pages/` 配下が実際の output 対象です。
+
+- `*.njk` は末尾の `.njk` だけを外して render されます（例: `index.html.njk` → `index.html`）
+- CSS / SVG などそれ以外は copy されます
+- `pages/` からの相対構造は output でも維持されます
+
+公式 sample のページ構成:
+
+| グループ | 内容 |
+| -------- | ---- |
+| Portal | `pages/index.html.njk` |
+| dashboard/ | Dashboard 画面と page-local CSS |
+| crud/ | 一覧・詳細・登録・編集・削除・完了などの画面群 |
+| wizard/ | 入力・確認・完了の画面群 |
+
+## 共通 asset
+
+共通で使う asset の例:
+
+| source | output |
+| ------ | ------ |
+| [`pages/assets/css/common.css`](../../src/sample/pages/assets/css/common.css) | `dist/sample/assets/css/common.css` |
+| [`pages/assets/img/logo.svg`](../../src/sample/pages/assets/img/logo.svg) | `dist/sample/assets/img/logo.svg` |
+
+深い階層のページからも同じ共通 asset を参照するため、layout では `rootPath` を使います。
+
+```nunjucks
+<link rel="stylesheet" href="{{ rootPath }}assets/css/common.css">
+```
+
+`rootPath` は output 上のページ位置に応じて、output root までの相対パスを表します。  
+詳細は [files pipeline](07-files-pipeline.md) を参照してください。
+
+## Page-local asset
+
+画面グループ専用の CSS 例:
+
+| source | output |
+| ------ | ------ |
+| [`dashboard/.../dashboard.css`](../../src/sample/pages/dashboard/assets/css/dashboard.css) | `dist/sample/dashboard/assets/css/dashboard.css` |
+| [`crud/.../crud.css`](../../src/sample/pages/crud/assets/css/crud.css) | `dist/sample/crud/assets/css/crud.css` |
+| [`wizard/.../wizard.css`](../../src/sample/pages/wizard/assets/css/wizard.css) | `dist/sample/wizard/assets/css/wizard.css` |
+
+page-local CSS は、その画面グループからの相対パスで参照します。
+
+```html
+<link rel="stylesheet" href="assets/css/dashboard.css">
+```
+
+> **Warning**
+>
+> 次のように `rootPath` を付けて page-local CSS を参照しないでください。
+>
+> ```nunjucks
+> {{ rootPath }}assets/css/dashboard.css
+> ```
+>
+> `rootPath` は output root（`dist/sample/`）基準です。  
+> Dashboard 用 CSS は `dist/sample/dashboard/assets/...` にあるため、  
+> root 基準のパスでは見つかりません。
+
+共通 asset と page-local asset の比較:
+
+| 種類 | 置き場所の例 | 参照の考え方 |
+| ---- | ------------ | ------------ |
+| 共通 asset | `pages/assets/...` | `{{ rootPath }}assets/...` |
+| page-local asset | `pages/dashboard/assets/...` など | 同一グループからの相対パス（`assets/...`） |
+
+## dist/sample
+
+`dist/sample/` は build の output です。
+
+- 手で編集する source ではありません
+- 次の build で上書き・再生成されることがあります
+- 配布対象として使える通常の静的ファイルです
+- `layouts` / `components` はここへ出力されません
+
+## Source と output の対応
+
+| source | 処理 | output |
+| ------ | ---- | ------ |
+| `pages/index.html.njk` | render | `index.html` |
+| `pages/assets/css/common.css` | copy | `assets/css/common.css` |
+| `layouts/base.njk` | template root | 直接 output なし |
+| `components/header.njk` | template root | 直接 output なし |
+| `pages/crud/detail.html.njk` | render | `crud/detail.html` |
+| `pages/dashboard/assets/css/dashboard.css` | copy | `dashboard/assets/css/dashboard.css` |
+
+## どこを編集するか
+
+目的ごとの目安です。
+
+| 目的 | 主な編集先 |
+| ---- | ---------- |
+| ページ本文 | `pages/**/*.html.njk` |
+| 共通 layout | [`layouts/base.njk`](../../src/sample/layouts/base.njk) |
+| 共通 component | `components/*.njk` |
+| 全体の見た目 | [`pages/assets/css/common.css`](../../src/sample/pages/assets/css/common.css) |
+| 画面グループの見た目 | 各グループの `assets/css/*.css` |
+| build やサーバー設定 | `jskim.config.js` |
+
+日常の開発の流れは [基本的な開発workflow](04-basic-workflow.md)、  
+CLI と設定の詳細は [CLIリファレンス](05-cli-reference.md) / [設定](06-configuration.md) を参照してください。