@burger-editor/frozen-patty 4.0.0-alpha.70 → 4.0.0-alpha.71

package/README.md

@@ -1,54 +1,47 @@
-# frozen-patty
+# `@burger-editor/frozen-patty`
 
 [![npm version](https://badge.fury.io/js/@burger-editor%2Ffrozen-patty.svg)](https://badge.fury.io/js/@burger-editor%2Ffrozen-patty)
 
-Pure HTML to JSON converter that does not use a template engine.
+**テンプレートエンジン不要**で HTML ⇄ JSON 相互変換を行う軽量ライブラリ。`data-field` 属性ベースのマッピング契約だけで動作する。
 
-`frozen-patty`は、HTMLとJSONデータの間でシームレスな変換を行う軽量ライブラリです。テンプレートエンジンを必要とせず、HTMLからデータを抽出したり、データをHTMLに適用したりすることができます。BurgerEditorのコンテンツデータとHTML構造を担保するためのコア機能として開発されました。
+このパッケージは BurgerEditor のコンテンツ構造の核として組み込まれているが、**BurgerEditor とは独立した汎用ライブラリ**として単体利用できる。`data-field` で注釈した既存 HTML があれば、エディタやランタイムを介さず JSON 抽出・JSON マージが可能。
 
-## 特徴
+## Installation
 
-- 🔄 HTMLからJSONへの抽出とJSONからHTMLへの適用
-- 🪶 軽量で依存関係が少ない
-- 🌟 テンプレートエンジン不要
-- 📝 カスタム属性名のサポート
-- 🧩 データ型の自動変換オプション
-- 🔧 高度なカスタマイズが可能
-- 📋 複数のフィールドと配列データの対応
-- 🛡️ XSS対策機能
+```sh
+yarn add -D @burger-editor/frozen-patty
+```
 
-## インストール
+## Related Packages
 
-```
-$ npm install -D @burger-editor/frozen-patty
-```
+| パッケージ              | 関係                                    | このパッケージとの使い分け                                                                  |
+| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `@burger-editor/core`   | 上位（core が frozen-patty を内部利用） | ブロック構造・編集エンジンが必要なら core。HTML ⇄ JSON だけで十分なら本パッケージ単独で完結 |
+| `@burger-editor/client` | 上位（間接利用）                        | ブラウザ編集 UI を伴う場合のみ                                                              |
+| `@burger-editor/blocks` | 連携                                    | 標準アイテム定義の HTML ⇄ JSON 変換に内部利用される                                         |
 
-## 基本的な使い方
+frozen-patty 単独で足りるケースは「`data-field` 注釈 HTML ↔ JSON の往復だけ」。コンテンツの編集 UI やブロック並べ替えが必要になった時点で core / client を追加する。
 
-### データの抽出 (HTML → JSON)
+## Usage
 
-```js
+### HTML → JSON
+
+```ts
 import frozenPatty from '@burger-editor/frozen-patty';
 
-// 基本的な使い方
-frozenPatty('<div data-field="text">value</div>').toJSON(); // => { text: 'value' }
-frozenPatty('<div data-field="field-name">value</div>').toJSON(); // => { 'field-name': 'value' }
+frozenPatty('<div data-field="text">value</div>').toJSON();
+// => { text: 'value' }
 
-// 属性値の抽出
-frozenPatty('<a href="http://localhost" data-field="href:href">link</a>').toJSON(); // => { 'href': 'http://localhost' }
+frozenPatty('<a href="http://localhost" data-field="href:href">link</a>').toJSON();
+// => { href: 'http://localhost' }
 
-// カスタム属性名の使用
-frozenPatty('<div data-bge="text">value</div>', { attr: 'bge' }).toJSON(); // => { text: 'value' }
+frozenPatty('<div data-bge="text">value</div>', { attr: 'bge' }).toJSON();
+// => { text: 'value' }
 ```
 
-### データの適用 (JSON → HTML)
-
-```js
-// 既存のHTMLにデータをマージする
-frozenPatty('<div data-field="text">value</div>').merge({ text: 'merged' }).toHTML();
-// => "<div data-field="text">merged</div>";
+### JSON → HTML
 
-// 複数のフィールドを持つHTMLにデータをマージする
+```ts
 const html = `
 	<div>
 		<h1 data-field="title">Old Title</h1>
@@ -57,117 +50,40 @@ const html = `
 	</div>
 `;
 
-const data = {
-	title: 'New Title',
-	description: 'Updated description',
-	link: 'https://example.com',
-};
-
-frozenPatty(html).merge(data).toHTML();
+frozenPatty(html)
+	.merge({
+		title: 'New Title',
+		description: 'New description',
+		link: 'https://example.com',
+	})
+	.toHTML();
 ```
 
-各フィールドが更新されたHTMLが返されます
+## `data-field` 属性 DSL
 
-結果のHTML:
+`data-field`（または `attr` オプションで指定したカスタム属性）は、HTML ⇄ JSON のマッピング契約を定義する。
 
-```html
-<div>
-	<h1 data-field="title">New Title</h1>
-	<p data-field="description">Updated description</p>
-	<a data-field="link:href" href="https://example.com">Click here</a>
-</div>
-```
+### 構文一覧
 
-## data-field属性のシンタックス
+| 形式                        | 抽出 / 適用先                                                     | 例                                                   |
+| --------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- |
+| `data-field="name"`         | テキスト/`textContent`（フォーム要素は `value`）                  | `<div data-field="title">T</div>`                    |
+| `data-field="name:attr"`    | 指定属性 `attr` の値を `name` キーに対応付け                      | `<a data-field="link:href" href="/">…</a>`           |
+| `data-field=":attr"`        | ショートハンド: 属性名そのものをフィールド名に使う                | `<a data-field=":href" href="/">…</a>`               |
+| `data-field-foo="bar"`      | `data-field` 属性自体を省略した形。`data-field=":foo"` で参照可能 | `<div data-field=":foo" data-field-foo="bar"></div>` |
+| `data-field="f1:a1, f2:a2"` | カンマ区切りで同一要素に複数フィールドをバインド                  | `<a data-field="link:href, tip:title">…</a>`         |
 
-`data-field`属性（またはカスタム属性名）は、HTMLからデータを抽出する際のマッピングと、JSONデータをHTMLに適用する際の対象を定義します。
+`data-field=":foo"` のショートハンドは、要素に IDL 属性として `foo` が存在しない場合に限り、`data-field-foo` 属性を参照する動作にフォールバックする。
 
-### 基本形式
-
-```
-data-field="フィールド名"
-```
-
-**抽出時**：要素の内容を「フィールド名」というキーでJSONに抽出します。
-
-- input、select、textareaなどのフォーム要素の場合は`value`プロパティ
-- その他の要素の場合はHTMLを含む`innerHTML`の内容
-
-**適用時**：「フィールド名」に対応するJSONの値が要素の内容に反映されます。
-
-- input、select、textareaなどのフォーム要素の場合は`value`プロパティに反映
-- その他の要素の場合は`innerHTML`に反映（HTMLタグも解釈される）
-- `innerHTML`に反映されるHTMLは`xssSanitize`オプションに依存し適切にサニタイズされます
-
-### 属性値の指定
-
-```
-data-field="フィールド名:属性名"
-```
+### 特別な属性名
 
-**抽出時**：要素の指定された属性の値を「フィールド名」というキーでJSONに抽出します。
-例: `data-field="href:href"`は`href`属性の値をJSONの`href`キーに抽出します。
+| 属性名 | セマンティクス                                                                         |
+| ------ | -------------------------------------------------------------------------------------- |
+| `text` | 要素のテキストコンテンツ（HTML タグを除いた文字列）                                    |
+| `html` | 要素の `innerHTML`                                                                     |
+| `node` | 要素のタグ名。**適用時は要素そのものを置換**するため、イベントハンドラ・参照は失われる |
 
-**適用時**：「フィールド名」に対応するJSONの値が要素の指定された属性に反映されます。
-例: `data-field="href:href"`でJSONに`{ href: "https://example.com" }`がある場合、要素の`href`属性が更新されます。
-
-特別な属性名：
-
-- `text` - 要素のテキストコンテンツを取得/設定（HTMLタグを除いたコンテンツ）
-- `html` - 要素のHTML内容を取得/設定（`innerHTML`と同じ）
-- `node` - 要素名（タグ名）を取得/設定（**注意**: 設定時は要素そのものを置き換える強力な操作のため、イベントハンドラや参照は失われます）
-
-### 属性名の省略
-
-```
-data-field=":属性名"
-```
-
-**抽出時**：フィールド名を省略すると、属性名自体がフィールド名として使用されます。
-例: `data-field=":href"`は`href`属性の値をJSONの`href`キーに抽出します。
-
-**適用時**：属性名と同じキーを持つJSONの値が、対応する属性に反映されます。
-例: `data-field=":href"`でJSONに`{ href: "https://example.com" }`がある場合、要素の`href`属性が更新されます。
-
-#### data-field-\* ショートハンド
-
-```
-data-field=":foo"
-```
-
-`:foo`のような指定の場合、要素に`foo`属性があるか探しにいきますが、要素に属性（正確にはIDL属性として）が存在しない場合、且つ要素に`data-field-foo`属性があれば、`data-field-foo`と見做されます。
-
-**抽出時**：`:foo`のように指定すると、元の`data-field-foo`属性から値を抽出します。
-例: `data-field=":foo"`は`data-field-foo`属性の値をJSONの`foo`キーに抽出します。
-
-```html
-<div data-field=":foo" data-field-foo="bar"></div>
-```
-
-これは `{ foo: "bar" }` というJSONに変換されます。
-
-**適用時**：フィールド名と同じ名前の`data-field-*`属性に値が反映されます。
-
-### 複数のフィールド指定
-
-```
-data-field="フィールド名1:属性名1, フィールド名2:属性名2"
-```
-
-**抽出時**：同じ要素から複数のデータを抽出します。カンマで区切ることで複数のフィールドを指定できます。
-
-**適用時**：各フィールド名に対応するJSONの値が、それぞれ指定された属性または内容に反映されます。
-
-例:
-
-```html
-<a href="/url" title="ヒント" data-field="link:href, tooltip:title">リンクテキスト</a>
-```
-
-これは `{ link: "/url", tooltip: "ヒント" }` というJSONに変換されます。
-逆に、`{ link: "/new-url", tooltip: "新しいヒント" }` というJSONを適用すると、hrefとtitle属性がそれぞれ更新されます。
-
-### 配列データの指定
+### 配列フィールド (`data-field-list`)
 
 ```html
 <ul data-field-list>
@@ -176,432 +92,123 @@ data-field="フィールド名1:属性名1, フィールド名2:属性名2"
 </ul>
 ```
 
-**抽出時**：同じ`data-field`値を持つ複数の要素からデータが配列として抽出されます。
-
-**適用時**：配列データが対応する要素に反映されます。
+- 抽出: 同一 `data-field` 値の要素群を配列としてシリアライズ
+- 適用: 配列長に合わせて DOM 要素数を自動増減
+  - データが多い場合: **最初の要素をテンプレート**として複製追加
+  - データが少ない場合: 余分な要素を削除
 
-- データの数が既存の要素より多い場合：最初の要素をテンプレートとして新しい要素が追加されます
-- データの数が既存の要素より少ない場合：余分な要素は削除されます
+### `picture` 要素の特別処理
 
-例: `{ items: ["新アイテム1", "新アイテム2", "新アイテム3"] }` というデータを適用すると、リストが3つの項目を持つように更新されます。
+`picture` は HTML 仕様（`source` が先、`img` が最後）と配列順序（`img` が先頭、`source` が後）が**逆**になる点に注意。
 
-### picture要素の特別処理
-
-`picture`要素は、レスポンシブ画像を実現するためのHTML要素で、`frozen-patty`では特別な処理を行っています：
-
-**抽出時**：HTMLから次のようなpicture要素がある場合を考えます。
+抽出例:
 
 ```html
-<!-- 元のHTML構造（HTML仕様に従い、source要素が先、img要素が後） -->
 <picture data-field-list>
 	<source
-		data-field="path:srcset, :width, :height, :media"
-		srcset="/path/to/large.jpg"
+		data-field="path:srcset, :width, :media"
+		srcset="/large.jpg"
 		width="1200"
-		height="900"
 		media="(min-width: 1000px)" />
 	<source
-		data-field="path:srcset, :width, :height, :media"
-		srcset="/path/to/medium.jpg"
+		data-field="path:srcset, :width, :media"
+		srcset="/medium.jpg"
 		width="800"
-		height="600"
 		media="(min-width: 600px)" />
-	<img
-		data-field="path:src, :alt, :width, :height"
-		src="/path/to/default.jpg"
-		alt="代替テキスト"
-		width="400"
-		height="300" />
+	<img data-field="path:src, :alt, :width" src="/default.jpg" alt="代替" width="400" />
 </picture>
 ```
 
-このHTMLから抽出する際に、以下の特別な考慮がされます：
-
-1. 配列データの順序：
-   - HTML内の`picture`要素では一般的に`source`要素が先に配置され、`img`要素が最後に配置されます
-   - 抽出されるデータの配列では逆順になり、img要素のデータが先、source要素のデータが後
-
-つまり、DOM内の配置順序（source要素が先、img要素が後）と、配列データ内の順序（img要素のデータが先、source要素のデータが後）は逆になります。
-
-上記のHTMLを変換すると、以下のようなJSONが生成されます：
-
-```js
-// HTMLからJSONへの変換
-const htmlString = document.querySelector('picture').outerHTML;
-const extractedData = frozenPatty(htmlString).toJSON();
-```
-
-抽出結果:
+→
 
 ```json
 {
-	"path": [
-		"/path/to/default.jpg", // インデックス0: img要素のsrc
-		"/path/to/medium.jpg", // インデックス1: 1つ目のsource要素のsrcset
-		"/path/to/large.jpg" // インデックス2: 2つ目のsource要素のsrcset
-	],
-	"alt": ["代替テキスト"], // 変換機構との一貫性のため配列
+	"path": ["/default.jpg", "/medium.jpg", "/large.jpg"],
+	"alt": ["代替"],
 	"width": [400, 800, 1200],
-	"height": [300, 600, 900],
-	"media": [
-		null, // 変換機構との一貫性のため配列となり、img要素にはmedia属性を持たないためnull固定
-		"(min-width: 600px)",
-		"(min-width: 1000px)"
-	]
+	"media": [null, "(min-width: 600px)", "(min-width: 1000px)"]
 }
 ```
 
-`picture`要素内の各要素（`source`や`img`）は内部的にリストとして扱われ、それぞれの属性（`srcset`, `width`, `media`など）も対応するインデックスを持つ配列としてデータが格納されます。そのため、`img`要素にしか通常存在しない`alt`属性や、`source`要素にしか存在しない`media`属性も、このデータ構造に合わせて**配列形式で表現されます**（対応する要素がない場合はnullが入ります）。
-
-**適用時**：JSONデータをHTMLに適用する際も特別な処理が行われます。例えば以下のJSONデータを適用すると：
-
-```js
-// 適用するJSONデータ
-const data = {
-	path: [
-		'/path/to/default.jpg', // インデックス0：img要素のsrc属性に設定（DOM内では最後）
-		'/path/to/medium.jpg', // インデックス1：source要素のsrcset属性に設定
-		'/path/to/large.jpg', // インデックス2：source要素のsrcset属性に設定
-		'/path/to/x-large.jpg', // インデックス3：source要素のsrcset属性に設定（DOM内では最初）
-	],
-	alt: ['レスポンシブ画像の説明'], // 抽出機構との互換性のためにimg要素でしか扱わないが配列として指定
-	width: [400, 800, 1200, 1600],
-	height: [300, 600, 900, 1200],
-	media: [
-		null, // img要素に対応するインデックスなのでnullを指定
-		'(min-width: 600px)', // source要素のmedia属性
-		'(min-width: 1000px)', // source要素のmedia属性
-		'(min-width: 1400px)', // source要素のmedia属性
-	],
-};
-```
-
-データを適用した結果、以下のようなHTMLが生成されます
-
-```html
-<picture data-field-list>
-	<source
-		data-field="path:srcset, :width, :height, :media"
-		srcset="/path/to/x-large.jpg"
-		width="1600"
-		height="1200"
-		media="(min-width: 1400px)" />
-	<source
-		data-field="path:srcset, :width, :height, :media"
-		srcset="/path/to/large.jpg"
-		width="1200"
-		height="900"
-		media="(min-width: 1000px)" />
-	<source
-		data-field="path:srcset, :width, :height, :media"
-		srcset="/path/to/medium.jpg"
-		width="800"
-		height="600"
-		media="(min-width: 600px)" />
-	<img
-		data-field="path:src, :alt, :width, :height"
-		src="/path/to/default.jpg"
-		alt="レスポンシブ画像の説明"
-		width="400"
-		height="300" />
-</picture>
-```
-
-適用時には以下の特別処理が行われます：
-
-1. 要素の配置と変換：
-   - 配列の最初の要素（インデックス0）は`img`要素に変換され、DOMでは最後に配置されます
-   - 配列の2番目以降の要素は`source`要素に変換され、配列の逆順にDOMに挿入されます（配列の末尾から先頭方向に）
-
-2. 属性の自動変換：
-   - `img`要素：`srcset`属性は`src`属性に変換され、`sizes`属性は削除されます
-   - `source`要素：`src`属性は`srcset`属性に変換され、`alt`属性と`loading`属性は削除されます
-   - `data-field`属性のシンタックスは、それぞれの要素に対応する属性名に再設定されます
-     - `img`要素: `data-field="path:src, :alt, :width, :height"`
-     - `source`要素: `data-field="path:srcset, :width, :height, :media"`
-
-3. 順序の反転：
-   - 配列データ内の順序：[0, 1, 2, 3]
-   - 生成されるHTML内の順序：[3, 2, 1, 0]（0がimg要素）
-
-この特別処理により、HTML標準に準拠した`picture`要素が正しく生成され、ブラウザのレスポンシブ画像機能が適切に動作します。
+適用時の自動変換ルール:
 
-## 高度な使い方
+| 配列インデックス | 生成要素 | DOM 位置                       | 属性変換                                 |
+| ---------------- | -------- | ------------------------------ | ---------------------------------------- |
+| `0`              | `img`    | DOM 末尾                       | `srcset` → `src`、`sizes` 削除           |
+| `1..n`           | `source` | DOM 先頭側（配列の逆順で挿入） | `src` → `srcset`、`alt` / `loading` 削除 |
 
-### データ型の自動変換
+`data-field` 構文も生成要素に合わせて再設定される（`img`: `path:src, …` / `source`: `path:srcset, …`）。配列要素に該当属性が存在しないスロット（例: `img` の `media`）は `null` で埋める。
 
-文字列を適切なデータ型に自動変換するオプションがあります：
+## Options
 
-```js
-const html = `
-	<div data-field="isActive">true</div>
-	<div data-field="count">5</div>
-	<div data-field="price">10.5</div>
-`;
+`frozenPatty(html, options)` の第 2 引数。
 
-const data = frozenPatty(html, {
-	typeConvert: true,
-}).toJSON();
-// => { isActive: true, count: 5, price: 10.5 }
-// 文字列ではなく、適切な型に変換されます
-```
+| Option        | Type                 | Default   | 説明                                                                          |
+| ------------- | -------------------- | --------- | ----------------------------------------------------------------------------- |
+| `attr`        | `string`             | `"field"` | フィールド属性名（`data-` プレフィックスを除いた部分）。`"bge"` で `data-bge` |
+| `typeConvert` | `boolean`            | `false`   | `"true"` → `true`、`"5"` → `5`、`"10.5"` → `10.5` の自動型変換                |
+| `valueFilter` | `<T>(value: T) => T` | -         | 値変換フィルタ。`merge()` と `toJSON()` に適用。`toJSON(false)` で無効化可能  |
+| `xssSanitize` | `boolean`            | `true`    | HTML 挿入時の XSS サニタイズ                                                  |
 
-### 値フィルタの使用
+### XSS サニタイズが除去する対象
 
-抽出または適用時に値をカスタマイズするフィルタ関数を提供できます：
+`xssSanitize: true`（デフォルト）で、`html` 系の挿入時に以下を除去する。
 
-```js
-const valueFilter = (value) => {
-	if (typeof value === 'string') {
-		return value.toUpperCase();
-	}
-	return value;
-};
+**タグ**:
 
-const html = '<div data-field="text">hello world</div>';
-const data = frozenPatty(html, {
-	valueFilter,
-}).toJSON();
-// => { text: 'HELLO WORLD' }
 ```
-
-これは`merge()`と`toJSON()`どちらの場合でも適用されますが、`toJSON`だけは`toJSON(false)`とすると無効化できます。
-
-### 複数の属性と値を同時に扱う
-
-同じ要素から複数の属性や値を抽出することができます：
-
-```js
-const html =
-	'<div data-attr="attr-value" data-field="text, attr:data-attr">text-value</div>';
-frozenPatty(html).toJSON();
-// => { text: 'text-value', attr: 'attr-value' }
-```
-
-### リスト（配列）データの取得
-
-`data-field-list`属性を使用して、同じフィールド名の要素から配列データを抽出できます：
-
-```js
-const html = `
-	<ul data-field-list>
-		<li data-field="items">Item 1</li>
-		<li data-field="items">Item 2</li>
-		<li data-field="items">Item 3</li>
-	</ul>
-`;
-
-frozenPatty(html).toJSON();
-// => { items: ['Item 1', 'Item 2', 'Item 3'] }
+script, style, template, object, embed, iframe, frame, frameset, applet
 ```
 
-### 複合的なデータの抽出と適用
+**属性**:
 
-複雑なHTMLから構造化されたデータを抽出する例：
+- `on*` で始まるイベントハンドラ属性（`onclick`、`onerror` ほか）
+- `href` / `src` / `action` などの URL 属性のうち、`javascript:` / `data:` / `vbscript:` で始まる値
 
-```js
-const html = `
-	<div>
-		<div data-field="title">商品タイトル</div>
-		<div data-field="content"><span>HTML内容</span></div>
-		<div data-field="meta:data-custom" data-custom="メタデータ"></div>
-		<ul data-field-list>
-			<li data-field="tags">タグ1</li>
-			<li data-field="tags">タグ2</li>
-		</ul>
-		<ul data-field-list>
-			<li><a data-field="links:href, linkTexts" href="/page1">リンク1</a></li>
-			<li><a data-field="links:href, linkTexts" href="/page2">リンク2</a></li>
-		</ul>
-	</div>
-`;
-
-const data = frozenPatty(html).toJSON();
-// => {
-//   title: '商品タイトル',
-//   content: '<span>HTML内容</span>',
-//   meta: 'メタデータ',
-//   tags: ['タグ1', 'タグ2'],
-//   links: ['/page1', '/page2'],
-//   linkTexts: ['リンク1', 'リンク2']
-// }
-
-// データを更新してHTMLを生成
-const updatedData = {
-	title: '新しいタイトル',
-	tags: ['新タグ1', '新タグ2', '新タグ3'], // 要素が増えても対応
-	links: ['/new1', '/new2'],
-	linkTexts: ['新リンク1', '新リンク2'],
-};
-
-const updatedHtml = frozenPatty(html).merge(updatedData).toHTML();
-// => 更新されたHTMLが返されます
-```
-
-### DOM要素の取得
-
-HTML文字列ではなくDOM要素として結果を取得することもできます：
-
-```js
-const element = frozenPatty(html).merge(data).toDOM();
-// => DOM Element
-```
-
-### XSS対策機能
-
-`frozen-patty`はデフォルトでDOM-based XSS攻撃を防止するセキュリティ機能を備えています。
-
-```js
-// デフォルトでXSS対策が有効
-const fp = frozenPatty('<div data-field="content">コンテンツ</div>');
-
-// XSS対策を無効化したい場合
-const fpUnsafe = frozenPatty('<div data-field="content">コンテンツ</div>', {
-	xssSanitize: false,
-});
-
-// 危険なHTMLを含むデータを適用する例
-const data = {
-	content: '<script>alert("XSS");</script><p>安全なコンテンツ</p>',
-};
-
-// 安全に処理（scriptタグは削除される）
-fp.merge(data).toHTML();
-// 結果: <div data-field="content"><p>安全なコンテンツ</p></div>
-
-// XSS対策を無効化した場合（非推奨）
-fpUnsafe.merge(data).toHTML();
-// 結果: <div data-field="content"><script>alert("XSS");</script><p>安全なコンテンツ</p></div>
-```
-
-以下のセキュリティ対策が実装されています：
-
-1. 危険な要素の削除：
-   - `script`, `style`, `template`, `object`, `embed`, `iframe`, `frame`, `frameset`, `applet`
-
-2. 危険な属性の削除：
-   - on\*で始まるイベントハンドラ属性
-   - javascript:, data:, vbscript: で始まるURLを受け取る`href`、`src`、`action`などの属性
-
-信頼できない外部データを扱う場合は、必ずデフォルト設定（XSS対策有効）を使用してください。
-
-### 要素の再生成と参照の扱いに関する注意事項
-
-`frozen-patty`はデータ適用時に新しい要素を生成します。これにより以下の点に注意が必要です：
-
-```js
-// 元のHTML要素
-const containerEl = document.querySelector('.container');
-const myElement = containerEl.querySelector('.my-element');
-
-// JavaScriptで要素に対してイベントハンドラを追加
-myElement.addEventListener('click', () => {
-	console.log('クリックされました');
-});
-
-// frozenPattyでデータを適用
-const htmlString = myElement.outerHTML;
-const newHtml = frozenPatty(htmlString).merge({ text: '新しいテキスト' }).toHTML();
-
-// 新しいHTML文字列で要素を更新する方法1: innerHTML + replaceChild
-const tempDiv = document.createElement('div');
-tempDiv.innerHTML = newHtml;
-containerEl.replaceChild(tempDiv.firstElementChild, myElement);
-
-// ⚠️ 警告: この時点でイベントハンドラは失われています
-```
-
-または、insertAdjacentHTMLを使う方法もあります：
-
-```js
-// 方法2: insertAdjacentHTML + remove
-myElement.insertAdjacentHTML('afterend', newHtml);
-const newElement = myElement.nextElementSibling;
-myElement.remove();
-
-// こちらの方法でも同様にイベントハンドラは失われます
-```
-
-この要素の再生成は`toHTML`だけでなく`toDOM`を使用したときにも同様です。
-
-特に以下の点に注意してください：
-
-1. **イベントハンドラの喪失**: JavaScript で動的に追加したイベントハンドラは、HTML操作（`outerHTML`/`innerHTML`）では保持されません
-
-2. **オブジェクト参照の更新**: 元の要素への参照（変数）は、新しい要素を生成した後も自動的に更新されません
-
-3. **nodeディレクティブの影響**: `node`ディレクティブは要素そのものを置き換えるため、変更が特に大きくなります
-
-これらの問題を回避するには、以下の方法があります：
-
-- HTML操作後に再度要素を取得し、イベントハンドラを再設定する
-- イベントの委譲（親要素でのイベント管理）を利用する
-- イベント管理とHTML操作を分離した設計にする
+信頼できない外部データを扱う場合は、必ずデフォルト（`xssSanitize: true`）のまま使用すること。
 
 ## API
 
-### `frozenPatty(html[, options])`
-
-HTMLからデータを抽出するメインの関数です。
-
-#### Parameters
-
-| parameter | type     | required | descriptions               |
-| --------- | -------- | -------- | -------------------------- |
-| html      | `string` | required | 元のHTML文字列             |
-| options   | `Object` | optional | オプション設定（以下参照） |
-
-#### Options
+| Method              | 戻り値    | 説明                                                                      |
+| ------------------- | --------- | ------------------------------------------------------------------------- |
+| `merge(data)`       | `this`    | JSON データを HTML にマージ                                               |
+| `toJSON(filtering)` | `object`  | HTML → JSON。`filtering = false` で `valueFilter` をスキップ（既定 true） |
+| `toHTML()`          | `string`  | 結果を HTML 文字列で取得                                                  |
+| `toDOM()`           | `Element` | 結果を DOM 要素で取得                                                     |
 
-| options     | type                            | default   | descriptions                                                                    |
-| ----------- | ------------------------------- | --------- | ------------------------------------------------------------------------------- |
-| attr        | string                          | `"field"` | フィールドとして扱うノードを指定するための**データ属性**名                      |
-| typeConvert | boolean                         | `false`   | データ属性の値の自動型変換を有効にします（"true"→true, "5"→5, "10.5"→10.5など） |
-| valueFilter | Function (`<T>(value: T) => T`) | -         | 値を処理するカスタムフィルタ関数                                                |
-| xssSanitize | boolean                         | `true`    | XSS対策機能を有効にします。危険なHTMLコードを自動的に除去します                 |
+## 要素再生成に関する注意
 
-### `merge(data)`
+`merge()` を経た `toHTML()` / `toDOM()` は**新しい要素を生成**する。元 DOM への参照および JavaScript で追加した**イベントハンドラは引き継がれない**。
 
-JSONデータをHTMLにマージします。
+```ts
+const el = document.querySelector('.my-element');
+el.addEventListener('click', handler);
 
-| args | type     | required | descriptions |
-| ---- | -------- | -------- | ------------ |
-| data | `Object` | required | 新しいデータ |
-
-### `toJSON([filtering])`
-
-HTMLからJSONデータに変換します。
-
-| args      | type      | default | descriptions                                                              |
-| --------- | --------- | ------- | ------------------------------------------------------------------------- |
-| filtering | `boolean` | `true`  | `true`の場合、コンストラクタで指定した`valueFilter`オプションを適用します |
-
-### `toHTML()`
-
-HTML文字列に変換します。
-
-### `toDOM()`
+const newHtml = frozenPatty(el.outerHTML).merge({ text: '新' }).toHTML();
+el.outerHTML = newHtml; // ← この時点で handler は失われる
+```
 
-DOM要素に変換します。
+特に `node` 属性は要素のタグそのものを置換するため影響が最も大きい。回避策:
 
-## サブモジュールエクスポート
+- 適用後に要素を再取得してイベントを張り直す
+- 親要素でのイベント委譲を採用する
+- DOM 操作とイベント管理レイヤーを分離した設計にする
 
-メインの`frozenPatty`関数以外に、個別の機能をサブモジュールとしてインポートできます。
+## サブパス Export
 
-| エクスポートパス                        | 説明                                                           |
-| --------------------------------------- | -------------------------------------------------------------- |
-| `@burger-editor/frozen-patty`           | メインの `frozenPatty` 関数                                    |
-| `@burger-editor/frozen-patty/get-value` | HTML要素からフィールド値を取得する `getValue` 関数             |
-| `@burger-editor/frozen-patty/set-value` | HTML要素にフィールド値を設定する `setValue`, `setContent` 関数 |
-| `@burger-editor/frozen-patty/utils`     | HTML正規化、フィールドパースなどのユーティリティ               |
-| `@burger-editor/frozen-patty/types`     | TypeScript型定義                                               |
+| パス                                    | 説明                                                        |
+| --------------------------------------- | ----------------------------------------------------------- |
+| `@burger-editor/frozen-patty`           | メインの `frozenPatty` 関数                                 |
+| `@burger-editor/frozen-patty/get-value` | HTML 要素からフィールド値を取得する `getValue`              |
+| `@burger-editor/frozen-patty/set-value` | HTML 要素にフィールド値を設定する `setValue` / `setContent` |
+| `@burger-editor/frozen-patty/utils`     | HTML 正規化、フィールドパースなどのユーティリティ           |
+| `@burger-editor/frozen-patty/types`     | TypeScript 型定義                                           |
 
-```js
-// サブモジュールの個別インポート例
-import { setValue } from '@burger-editor/frozen-patty/set-value';
+```ts
 import { getValue } from '@burger-editor/frozen-patty/get-value';
+import { setValue } from '@burger-editor/frozen-patty/set-value';
 ```
 
-## ライセンス
+## License
 
-MIT
+Dual Licensed under MIT OR Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@burger-editor/frozen-patty",
-	"version": "4.0.0-alpha.70",
+	"version": "4.0.0-alpha.71",
 	"description": "Pure HTML to JSON converter that does not use a template engine.",
 	"author": "D-ZERO",
 	"license": "(MIT OR Apache-2.0)",
@@ -32,6 +32,10 @@
 		},
 		"./types": {
 			"types": "./dist/types.d.ts"
+		},
+		"./parse-fields": {
+			"import": "./dist/parse-fields.js",
+			"types": "./dist/parse-fields.d.ts"
 		}
 	},
 	"files": [
@@ -43,7 +47,7 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@burger-editor/utils": "4.0.0-alpha.70"
+		"@burger-editor/utils": "4.0.0-alpha.71"
 	},
-	"gitHead": "522c1c4116ee40a4d3a462010101d1efc97c3c7d"
+	"gitHead": "c1f332e5de38a97b5fb901ccd3b28e2d49e65f53"
 }