@burger-editor/utils 4.0.0-alpha.6 → 4.0.0-alpha.60

package/README.md

@@ -1,3 +1,251 @@
-# utils
+# @burger-editor/utils
 
 [![npm version](https://badge.fury.io/js/@burger-editor%2Futils.svg)](https://badge.fury.io/js/@burger-editor%2Futils)
+
+BurgerEditorで使用する共通ユーティリティ関数集です。
+
+## 概要
+
+`@burger-editor/utils`は、BurgerEditorのコアパッケージや関連パッケージで共有される汎用ユーティリティ関数を提供します。文字列変換、マークダウン処理、日付フォーマット、HTML操作などの機能を含みます。
+
+## インストール
+
+```bash
+npm install @burger-editor/utils
+```
+
+または
+
+```bash
+yarn add @burger-editor/utils
+```
+
+## 提供される関数
+
+### 文字列ケース変換
+
+#### `camelCase(str: string): string`
+
+ケバブケース文字列をキャメルケースに変換します。
+
+```typescript
+import { camelCase } from '@burger-editor/utils';
+
+camelCase('my-property-name'); // => 'myPropertyName'
+camelCase('background-color'); // => 'backgroundColor'
+```
+
+#### `kebabCase(str: string): string`
+
+キャメルケース文字列をケバブケースに変換します。
+
+```typescript
+import { kebabCase } from '@burger-editor/utils';
+
+kebabCase('myPropertyName'); // => 'my-property-name'
+kebabCase('backgroundColor'); // => 'background-color'
+```
+
+### マークダウン変換
+
+#### `markdownToHtml(markdown: string): string`
+
+MarkdownテキストをHTMLに変換します。
+
+```typescript
+import { markdownToHtml } from '@burger-editor/utils';
+
+const html = markdownToHtml('# 見出し\n\n**太字**のテキスト');
+// => '<h1>見出し</h1>\n<p><strong>太字</strong>のテキスト</p>'
+```
+
+#### `htmlToMarkdown(html: string): string`
+
+HTMLをMarkdownテキストに変換します。
+
+```typescript
+import { htmlToMarkdown } from '@burger-editor/utils';
+
+const markdown = htmlToMarkdown('<h1>見出し</h1><p><strong>太字</strong></p>');
+// => '# 見出し\n\n**太字**'
+```
+
+### テキストフォーマット
+
+#### `nl2br(text: string): string`
+
+改行コードを`<br />`タグに変換します。
+
+```typescript
+import { nl2br } from '@burger-editor/utils';
+
+nl2br('行1\n行2\r\n行3');
+// => '行1<br />行2<br />行3'
+```
+
+#### `br2nl(html: string): string`
+
+`<br>`タグを改行コード（`\r\n`）に変換します。
+
+```typescript
+import { br2nl } from '@burger-editor/utils';
+
+br2nl('行1<br>行2<br />行3');
+// => '行1\r\n行2\r\n行3'
+```
+
+### 数値・日付フォーマット
+
+#### `formatByteSize(byteSize: number, digits?: number, autoFormat?: boolean): string`
+
+バイト数を人間が読みやすい形式にフォーマットします。
+
+```typescript
+import { formatByteSize } from '@burger-editor/utils';
+
+formatByteSize(1024); // => '1.00kB'
+formatByteSize(1048576); // => '1.00MB'
+formatByteSize(1536, 1); // => '1.5kB'
+formatByteSize(500, 2, false); // => '500byte'
+```
+
+#### `formatDate(timestamp: number, format: string): string`
+
+Unixタイムスタンプを指定したフォーマットの日付文字列に変換します。
+
+```typescript
+import { formatDate } from '@burger-editor/utils';
+
+formatDate(1704067200, 'YYYY-MM-DD'); // => '2024-01-01'
+formatDate(1704067200, 'YYYY年MM月DD日'); // => '2024年01月01日'
+```
+
+### URL・パス処理
+
+#### `origin(): string`
+
+現在のURLのオリジン（プロトコル + ホスト + ポート）を取得します。
+
+```typescript
+import { origin } from '@burger-editor/utils';
+
+// ブラウザで http://localhost:3000/page にアクセスしている場合
+origin(); // => 'http://localhost:3000'
+```
+
+#### `parseYTId(idOrUrl: string): string`
+
+YouTube URLから動画IDを抽出します。
+
+```typescript
+import { parseYTId } from '@burger-editor/utils';
+
+parseYTId('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
+// => 'dQw4w9WgXcQ'
+
+parseYTId('https://youtu.be/dQw4w9WgXcQ');
+// => 'dQw4w9WgXcQ'
+
+parseYTId('dQw4w9WgXcQ');
+// => 'dQw4w9WgXcQ'
+```
+
+#### `getBackgroundImagePath(value: string): string`
+
+CSS `background-image` プロパティ値からパスを抽出します。
+
+```typescript
+import { getBackgroundImagePath } from '@burger-editor/utils';
+
+getBackgroundImagePath('url("/images/bg.jpg")');
+// => '/images/bg.jpg'
+
+getBackgroundImagePath("url('https://example.com/bg.png')");
+// => 'https://example.com/bg.png'
+```
+
+### バリデーション
+
+#### `isValidAsClassName(className: string): boolean`
+
+文字列が有効なCSSクラス名かどうかをチェックします。
+
+```typescript
+import { isValidAsClassName } from '@burger-editor/utils';
+
+isValidAsClassName('my-class'); // => true
+isValidAsClassName('_private'); // => true
+isValidAsClassName('123invalid'); // => false
+isValidAsClassName('my class'); // => false
+```
+
+### HTML操作
+
+#### `strToDOM(html: string): HTMLElement`
+
+HTML文字列をDOM要素に変換します。
+
+```typescript
+import { strToDOM } from '@burger-editor/utils';
+
+const element = strToDOM('<div class="container">コンテンツ</div>');
+// => HTMLDivElement
+```
+
+#### `normalizeHtml(html: string): string`
+
+HTMLを正規化します（空白の調整など）。
+
+```typescript
+import { normalizeHtml } from '@burger-editor/utils';
+
+const normalized = normalizeHtml('<div>  content  </div>');
+```
+
+#### `replaceCommentWithHTML(template: string, items: Record<string, string>, replacer: Function): string`
+
+テンプレート内のコメントマーカーをHTMLに置き換えます。
+
+```typescript
+import { replaceCommentWithHTML } from '@burger-editor/utils';
+
+const template = '<div><!-- item:text --></div>';
+const items = { text: '<p>テキスト</p>' };
+const result = replaceCommentWithHTML(template, items, (_, itemHtml) => itemHtml);
+// => '<div><p>テキスト</p></div>'
+```
+
+### アイテム操作
+
+#### `mergeItems(itemSeeds: Record<string, ItemSeed>, customItems?: Record<string, ItemSeed>): Record<string, ItemSeed>`
+
+アイテム定義をマージします。
+
+```typescript
+import { mergeItems } from '@burger-editor/utils';
+
+const defaultItems = { text: textItemSeed };
+const customItems = { custom: customItemSeed };
+const merged = mergeItems(defaultItems, customItems);
+// => { text: textItemSeed, custom: customItemSeed }
+```
+
+## 依存関係
+
+- **dayjs** - 日付フォーマット処理
+- **marked** - Markdown to HTML変換
+- **turndown** - HTML to Markdown変換
+
+## 使用パッケージ
+
+このパッケージは以下のBurgerEditorパッケージで使用されています：
+
+- [@burger-editor/core](../core/)
+- [@burger-editor/blocks](../blocks/)
+- [@burger-editor/frozen-patty](../frozen-patty/)
+- [@burger-editor/migrator](../migrator/)
+- [@burger-editor/mcp-server](../mcp-server/)
+
+## ライセンス
+
+Dual Licensed under MIT OR Apache-2.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './camel-case.js';
 export * from './kebab-case.js';
 export * from './markdown.js';
+export * from './merge-items.js';
+export * from './normalize-html.js';
 export * from './replace-comment-with-html.js';
 export * from './utils.js';

package/dist/index.js

@@ -1,5 +1,7 @@
 export * from './camel-case.js';
 export * from './kebab-case.js';
 export * from './markdown.js';
+export * from './merge-items.js';
+export * from './normalize-html.js';
 export * from './replace-comment-with-html.js';
 export * from './utils.js';

package/dist/merge-items.d.ts

@@ -0,0 +1,35 @@
+/**
+ * マージ操作が可能な汎用型
+ * 任意のオブジェクト型にdeleteプロパティを追加する
+ */
+export type Mergeable<T extends Record<string, unknown>> = T & {
+    readonly delete?: boolean;
+};
+/**
+ * 汎用的なマージ関数
+ * 指定されたキーフィールドを基準にアイテムのマージを行う
+ * @param defaultItems デフォルトのアイテム配列
+ * @param mergeItems マージ設定配列
+ * @param keyField キーとなるフィールド名
+ * @param isValidForAdd 新規追加時のバリデーション関数
+ * @returns マージ後のアイテム配列
+ * @example
+ * ```typescript
+ * // SelectableValue型での使用例
+ * const result = mergeItems(
+ *   [{ value: 'a', label: 'A' }],
+ *   [{ value: 'b', label: 'B' }],
+ *   'value',
+ *   (item) => Boolean(item.label)
+ * );
+ *
+ * // 独自型での使用例
+ * interface User { id: string; name: string; }
+ * const users = mergeItems(
+ *   [{ id: '1', name: 'Alice' }],
+ *   [{ id: '2', name: 'Bob' }],
+ *   'id'
+ * );
+ * ```
+ */
+export declare function mergeItems<T extends Record<string, unknown>, K extends keyof T & string>(defaultItems: readonly T[], mergeItems: readonly Mergeable<Partial<T> & Pick<T, K>>[] | undefined, keyField: K, isValidForAdd?: (item: Mergeable<Partial<T> & Pick<T, K>>) => boolean): T[];

package/dist/merge-items.js

@@ -0,0 +1,57 @@
+/**
+ * 汎用的なマージ関数
+ * 指定されたキーフィールドを基準にアイテムのマージを行う
+ * @param defaultItems デフォルトのアイテム配列
+ * @param mergeItems マージ設定配列
+ * @param keyField キーとなるフィールド名
+ * @param isValidForAdd 新規追加時のバリデーション関数
+ * @returns マージ後のアイテム配列
+ * @example
+ * ```typescript
+ * // SelectableValue型での使用例
+ * const result = mergeItems(
+ *   [{ value: 'a', label: 'A' }],
+ *   [{ value: 'b', label: 'B' }],
+ *   'value',
+ *   (item) => Boolean(item.label)
+ * );
+ *
+ * // 独自型での使用例
+ * interface User { id: string; name: string; }
+ * const users = mergeItems(
+ *   [{ id: '1', name: 'Alice' }],
+ *   [{ id: '2', name: 'Bob' }],
+ *   'id'
+ * );
+ * ```
+ */
+export function mergeItems(defaultItems, mergeItems, keyField, isValidForAdd) {
+    // マージ設定がない場合はデフォルトをそのまま返す
+    if (!mergeItems) {
+        return [...defaultItems];
+    }
+    let result = [...defaultItems];
+    for (const mergeItem of mergeItems) {
+        if (mergeItem.delete) {
+            // 削除: キーが一致するものを除去
+            const keyValue = mergeItem[keyField];
+            result = result.filter((item) => item[keyField] !== keyValue);
+        }
+        else {
+            // 追加または更新
+            const keyValue = mergeItem[keyField];
+            const existingIndex = result.findIndex((item) => item[keyField] === keyValue);
+            if (existingIndex === -1) {
+                // 新規追加: バリデーション通過が必要
+                if (!isValidForAdd || isValidForAdd(mergeItem)) {
+                    result.push(mergeItem);
+                }
+            }
+            else {
+                // 既存の更新: マージする
+                result[existingIndex] = { ...result[existingIndex], ...mergeItem };
+            }
+        }
+    }
+    return result;
+}

package/dist/normalize-html.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTMLの構造を正規化して比較する
+ * 空白や属性順序の違いを無視し、タグ構造のみを比較する
+ * @param html1 比較対象のHTML文字列1
+ * @param html2 比較対象のHTML文字列2
+ * @returns 構造が同じ場合true、異なる場合false
+ */
+export declare function normalizeHtmlStructure(html1: string, html2: string): boolean;

package/dist/normalize-html.js

@@ -0,0 +1,109 @@
+/**
+ * HTMLの構造を正規化して比較する
+ * 空白や属性順序の違いを無視し、タグ構造のみを比較する
+ * @param html1 比較対象のHTML文字列1
+ * @param html2 比較対象のHTML文字列2
+ * @returns 構造が同じ場合true、異なる場合false
+ */
+export function normalizeHtmlStructure(html1, html2) {
+    const doc1 = new Range().createContextualFragment(html1);
+    const doc2 = new Range().createContextualFragment(html2);
+    return compareElements(doc1, doc2);
+}
+/**
+ * 2つの要素の構造を比較する
+ * @param el1 比較対象の要素1
+ * @param el2 比較対象の要素2
+ * @returns 構造が同じ場合true、異なる場合false
+ */
+function compareElements(el1, el2) {
+    // 子要素の数を取得（テキストノードは無視）
+    const children1 = [...el1.children];
+    const children2 = [...el2.children];
+    // 子要素の数が異なる場合は構造が異なる
+    if (children1.length !== children2.length) {
+        return false;
+    }
+    // 子要素がない場合（テキストのみまたは空要素）
+    if (children1.length === 0) {
+        // テキスト内容を正規化して比較
+        const text1 = normalizeText(el1.textContent ?? '');
+        const text2 = normalizeText(el2.textContent ?? '');
+        return text1 === text2;
+    }
+    // 各子要素を比較
+    for (const [i, child1] of children1.entries()) {
+        const child2 = children2[i];
+        if (!child1 || !child2 || !compareElementStructure(child1, child2)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * 2つの要素の構造を詳細に比較する
+ * @param el1 比較対象の要素1
+ * @param el2 比較対象の要素2
+ * @returns 構造が同じ場合true、異なる場合false
+ */
+function compareElementStructure(el1, el2) {
+    // タグ名が異なる場合は構造が異なる
+    if (el1.tagName !== el2.tagName) {
+        return false;
+    }
+    // 属性を比較（順序は無視）
+    const attrs1 = getNormalizedAttributes(el1);
+    const attrs2 = getNormalizedAttributes(el2);
+    if (!compareAttributes(attrs1, attrs2)) {
+        return false;
+    }
+    // 子要素を再帰的に比較
+    return compareElements(el1, el2);
+}
+/**
+ * 要素の属性を正規化して取得する
+ * @param el 対象の要素
+ * @returns 属性名をキー、属性値を値とするオブジェクト
+ */
+function getNormalizedAttributes(el) {
+    const attrs = {};
+    for (const attr of el.attributes) {
+        attrs[attr.name] = attr.value;
+    }
+    return attrs;
+}
+/**
+ * 2つの属性オブジェクトを比較する
+ * @param attrs1 比較対象の属性1
+ * @param attrs2 比較対象の属性2
+ * @returns 属性が同じ場合true、異なる場合false
+ */
+function compareAttributes(attrs1, attrs2) {
+    const keys1 = Object.keys(attrs1).toSorted();
+    const keys2 = Object.keys(attrs2).toSorted();
+    // 属性名の数が異なる場合は異なる
+    if (keys1.length !== keys2.length) {
+        return false;
+    }
+    // 各属性を比較
+    for (const [i, key1] of keys1.entries()) {
+        const key2 = keys2[i];
+        // 属性名が異なる場合は異なる
+        if (key1 !== key2) {
+            return false;
+        }
+        // 属性値が異なる場合は異なる
+        if (attrs1[key1] !== attrs2[key2]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * テキストを正規化する（空白文字を統一）
+ * @param text 対象のテキスト
+ * @returns 正規化されたテキスト
+ */
+function normalizeText(text) {
+    return text.replaceAll(/\s+/g, ' ').trim();
+}

package/dist/normalize-indent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * HTMLの先頭行のインデントを検出し、全行から同じインデントを削除する
+ *
+ * CRLF (\r\n) と LF (\n) の両方に対応
+ * @param html - 正規化するHTML文字列
+ * @returns インデントが正規化され、前後の空白行が削除されたHTML文字列
+ */
+export declare function normalizeIndent(html: string): string;

package/dist/normalize-indent.js

@@ -0,0 +1,18 @@
+/**
+ * HTMLの先頭行のインデントを検出し、全行から同じインデントを削除する
+ *
+ * CRLF (\r\n) と LF (\n) の両方に対応
+ * @param html - 正規化するHTML文字列
+ * @returns インデントが正規化され、前後の空白行が削除されたHTML文字列
+ */
+export function normalizeIndent(html) {
+    // 先頭の改行を削除
+    const trimmedHtml = html.replace(/^(?:\r?\n)+/, '');
+    const lines = trimmedHtml.split(/\r?\n/);
+    const firstLineIndent = lines[0]?.match(/^\s+/)?.[0] ?? '';
+    if (firstLineIndent.length === 0) {
+        return trimmedHtml;
+    }
+    const normalizedLines = lines.map((line) => line.replace(firstLineIndent, ''));
+    return normalizedLines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@burger-editor/utils",
-	"version": "4.0.0-alpha.6",
+	"version": "4.0.0-alpha.60",
 	"description": "BurgerEditor Editor Utility Functions",
 	"author": "D-ZERO",
 	"license": "(MIT OR Apache-2.0)",
@@ -26,12 +26,12 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"dayjs": "1.11.13",
-		"marked": "15.0.12",
-		"turndown": "7.2.0"
+		"dayjs": "1.11.19",
+		"marked": "17.0.2",
+		"turndown": "7.2.2"
 	},
 	"devDependencies": {
-		"@types/turndown": "5.0.5"
+		"@types/turndown": "5.0.6"
 	},
-	"gitHead": "33b78ba2472cd9b769df1d29caa4055884256874"
+	"gitHead": "edd68ff1a6fc82da87aec4c0b1150085dfdb80a4"
 }