fix: reorganized data structure and introduced component classes

README.md

@@ -53,8 +53,8 @@ npm install @conalog/patch-map
 
 #### CDN
 ```html
-<script src="https://cdn.jsdelivr.net/npm/pixi.js@8.9.2/dist/pixi.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/@conalog/patch-map@v0.1.9/dist/index.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/pixi.js@latest/dist/pixi.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@conalog/patch-map@latest/dist/index.umd.js"></script>
 ```
 
 ### Usage
@@ -67,27 +67,30 @@ const data = [
     type: 'group',
     id: 'group-id-1',
     label: 'group-label-1',
-    items: [{
+    children: [{
       type: 'grid',
       id: 'grid-1',
       label: 'grid-label-1',
       cells: [ [1, 0, 1], [1, 1, 1] ],
-      position: { x: 0, y: 0 },
-      itemSize: { width: 40, height: 80 },
-      components: [
-        {
-          type: 'background',
-          texture: {
-            type: 'rect',
-            fill: 'white',
-            borderWidth: 2,
-            borderColor: 'primary.dark',
-            radius: 4,
-          }
-        },
-        { type: 'icon', asset: 'loading', size: 16 }
-      ]
-    }]
+      gap: 4,
+      item: {
+        size: { width: 40, height: 80 },
+        components: [
+          {
+            type: 'background',
+            source: {
+              type: 'rect',
+              fill: 'white',
+              borderWidth: 2,
+              borderColor: 'primary.dark',
+              radius: 4,
+            }
+          },
+          { type: 'icon', source: 'loading', tint: 'black', size: 16 },
+        ]
+      },
+    }],
+    attrs: { x: 100, y: 100, },
   }
 ];
 
@@ -185,27 +188,30 @@ const data = [
     type: 'group',
     id: 'group-id-1',
     label: 'group-label-1',
-    items: [{
+    children: [{
       type: 'grid',
       id: 'grid-1',
       label: 'grid-label-1',
       cells: [ [1, 0, 1], [1, 1, 1] ],
-      position: { x: 0, y: 0 },
-      itemSize: { width: 40, height: 80 },
-      components: [
-        {
-          type: 'background',
-          texture: {
-            type: 'rect',
-            fill: 'white',
-            borderWidth: 2,
-            borderColor: 'primary.dark',
-            radius: 4,
-          }
-        },
-        { type: 'icon', asset: 'loading', size: 16 }
-      ]
-    }]
+      gap: 4,
+      item: {
+        size: { width: 40, height: 80 },
+        components: [
+          {
+            type: 'background',
+            source: {
+              type: 'rect',
+              fill: 'white',
+              borderWidth: 2,
+              borderColor: 'primary.dark',
+              radius: 4,
+            }
+          },
+          { type: 'icon', source: 'loading', tint: 'black', size: 16 },
+        ]
+      },
+    }],
+    attrs: { x: 100, y: 100, },
   }
 ];
 patchmap.draw(data);
@@ -220,24 +226,29 @@ For **detailed type definitions**, refer to the [data.d.ts](src/display/data-sch
 <br/>
 
 ### `update(options)`
-Updates the state of specific objects on the canvas. Use this to change properties like color or text visibility for already rendered objects.
+Updates the properties of objects rendered on the canvas. By default, only the changed properties are applied, but you can precisely control the update behavior using the `refresh` or `arrayMerge` options.
 
 #### **`Options`**
-- `path`(optional, string) - Selector for the object to which the event will be applied, following [jsonpath](https://github.com/JSONPath-Plus/JSONPath) syntax.
-- `elements`(optional, object \| array) - Direct references to one or more objects to update. Accepts a single object or an array. (Objects returned from [selector](#selectorpath), etc.).
-- `changes`(required, object) - New properties to apply (e.g., color, text visibility).
-- `saveToHistory`(optional, boolean \| string) - Determines whether to record changes made by this `update` method in the `undoRedoManager`. If a string that matches the historyId of a previously saved record is provided, the two records will be merged into a single undo/redo step.
-- `relativeTransform`(optional, boolean) - Determines whether to use relative values for `position`, `rotation`, and `angle`. If `true`, the provided values will be added to the object's values.
+- `path` (optional, string) - Selector for the object to which the event will be applied, following [jsonpath](https://github.com/JSONPath-Plus/JSONPath) syntax.
+- `elements` (optional, object \| array) - Direct references to one or more objects to update. Accepts a single object or an array. (Objects returned from [selector](#selectorpath), etc.).
+- `changes` (optional, object) - New properties to apply (e.g., color, text visibility). If the `refresh` option is set to `true`, this can be omitted.
+- `history` (optional, boolean \| string) - Determines whether to record changes made by this `update` method in the `undoRedoManager`. If a string that matches the historyId of a previously saved record is provided, the two records will be merged into a single undo/redo step.
+- `relativeTransform` (optional, boolean) - Determines whether to use relative values for `position`, `rotation`, and `angle`. If `true`, the provided values will be added to the object's values.
+- `arrayMerge` (optional, string) - Determines how to merge array properties. The default is `'merge'`.
+  - `'merge'` (default): Merges the target and source arrays.
+  - `'replace'`: Completely replaces the target array with the source array. Useful for forcing a specific state.
+- `refresh` (optional, boolean) - If set to `true`, all property handlers are forcibly re-executed and the object is "refreshed" even if the values in `changes` are the same as before. This is useful when child objects need to be recalculated due to changes in the parent. Default is `false`.
+
 
 ```js
 // Apply changes to objects with the label "grid-label-1"
 patchmap.update({
   path: `$..children[?(@.label=="grid-label-1")]`,
   changes: {
-    components: [
-      { type: 'icon', asset: 'wifi' }
-    ]
-  }
+    item: {
+      components: [{ type: 'icon', source: 'wifi' }],
+    },
+  },
 });
 
 // Apply changes to objects of type "group"
@@ -252,10 +263,16 @@ patchmap.update({
 patchmap.update({
   path: `$..children[?(@.type=="group")].children[?(@.type=="grid")]`,
   changes: {
-    components: [
-      { type: 'icon', tint: 'black' }
-    ]
-  }
+    item: {
+      components: [{ type: 'icon', tint: 'red' }],
+    },
+  },
+});
+
+// Force a full property update (refresh) for all objects of type "relations" using refresh: true
+patchmap.update({
+  path: `$..children[?(@.type==="relations")]`,
+  refresh: true
 });
 ```
 

README_KR.md

@@ -53,8 +53,8 @@ npm install @conalog/patch-map
 
 #### CDN
 ```html
-<script src="https://cdn.jsdelivr.net/npm/pixi.js@8.9.2/dist/pixi.min.js"></script>
-<script src="https://cdn.jsdelivr.net/npm/@conalog/patch-map@v0.1.9/dist/index.umd.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/pixi.js@latest/dist/pixi.min.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@conalog/patch-map@latest/dist/index.umd.js"></script>
 ```
 
 ### 기본 예제
@@ -67,27 +67,30 @@ const data = [
     type: 'group',
     id: 'group-id-1',
     label: 'group-label-1',
-    items: [{
+    children: [{
       type: 'grid',
       id: 'grid-1',
       label: 'grid-label-1',
       cells: [ [1, 0, 1], [1, 1, 1] ],
-      position: { x: 0, y: 0 },
-      itemSize: { width: 40, height: 80 },
-      components: [
-        {
-          type: 'background',
-          texture: {
-            type: 'rect',
-            fill: 'white',
-            borderWidth: 2,
-            borderColor: 'primary.dark',
-            radius: 4,
-          }
-        },
-        { type: 'icon', asset: 'loading', size: 16 }
-      ]
-    }]
+      gap: 4,
+      item: {
+        size: { width: 40, height: 80 },
+        components: [
+          {
+            type: 'background',
+            source: {
+              type: 'rect',
+              fill: 'white',
+              borderWidth: 2,
+              borderColor: 'primary.dark',
+              radius: 4,
+            }
+          },
+          { type: 'icon', source: 'loading', tint: 'black', size: 16 },
+        ]
+      },
+    }],
+    attrs: { x: 100, y: 100, },
   }
 ];
 
@@ -185,27 +188,30 @@ const data = [
     type: 'group',
     id: 'group-id-1',
     label: 'group-label-1',
-    items: [{
+    children: [{
       type: 'grid',
       id: 'grid-1',
       label: 'grid-label-1',
       cells: [ [1, 0, 1], [1, 1, 1] ],
-      position: { x: 0, y: 0 },
-      itemSize: { width: 40, height: 80 },
-      components: [
-        {
-          type: 'background',
-          texture: {
-            type: 'rect',
-            fill: 'white',
-            borderWidth: 2,
-            borderColor: 'primary.dark',
-            radius: 4,
-          }
-        },
-        { type: 'icon', texture: 'loading', size: 16 }
-      ]
-    }]
+      gap: 4,
+      item: {
+        size: { width: 40, height: 80 },
+        components: [
+          {
+            type: 'background',
+            source: {
+              type: 'rect',
+              fill: 'white',
+              borderWidth: 2,
+              borderColor: 'primary.dark',
+              radius: 4,
+            }
+          },
+          { type: 'icon', source: 'loading', tint: 'black', size: 16 },
+        ]
+      },
+    }],
+    attrs: { x: 100, y: 100, },
   }
 ];
 patchmap.draw(data);
@@ -219,24 +225,28 @@ draw method가 요구하는 **데이터 구조**입니다.
 <br/>
 
 ### `update(options)`
-캔버스에 이미 렌더링된 객체의 상태를 업데이트합니다. 색상이나 텍스트 가시성 같은 속성을 변경하는 데 사용하세요.
+캔버스에 렌더링된 객체의 속성을 업데이트합니다. 기본적으로 변경된 속성만 반영하지만, refresh 또는 arrayMerge 옵션을 통해 업데이트 동작을 정밀하게 제어할 수 있습니다.
 
 #### **`Options`**
-- `path`(optional, string) - [jsonpath](https://github.com/JSONPath-Plus/JSONPath) 문법에 따른 selector로, 이벤트가 적용될 객체를 선택합니다.
-- `elements`(optional, object \| array) - 업데이트할 하나 이상의 객체에 대한 직접 참조입니다. 단일 객체 또는 배열을 허용합니다. ([selector](#selectorpath)에서 반환된 객체 등).
-- `changes`(required, object) - 적용할 새로운 속성 (예: 색상, 텍스트 가시성).
-- `saveToHistory`(optional, boolean \| string) - 해당 `update` 메소드에 의한 변경 사항을 `undoRedoManager`에 기록할 것인지 결정합니다. 이전에 저장된 기록의 historyId와 일치하는 문자열이 제공되면, 두 기록이 하나의 실행 취소/재실행 단계로 병합됩니다.
-- `relativeTransform`(optional, boolean) - `position`, `rotation`, `angle` 값에 대해서 상대값을 이용할 지 결정합니다. 만약, `true` 라면 전달된 값을 객체의 값에 더합니다.
+- `path` (optional, string) - [jsonpath](https://github.com/JSONPath-Plus/JSONPath) 문법에 따른 selector로, 이벤트가 적용될 객체를 선택합니다.
+- `elements` (optional, object \| array) - 업데이트할 하나 이상의 객체에 대한 직접 참조입니다. 단일 객체 또는 배열을 허용합니다. ([selector](#selectorpath)에서 반환된 객체 등).
+- `changes` (optional, object) - 적용할 새로운 속성 (예: 색상, 텍스트 가시성). `refresh` 옵션을 `true`로 설정할 경우 생략할 수 있습니다.
+- `history` (optional, boolean \| string) - 해당 `update` 메소드에 의한 변경 사항을 `undoRedoManager`에 기록할 것인지 결정합니다. 이전에 저장된 기록의 historyId와 일치하는 문자열이 제공되면, 두 기록이 하나의 실행 취소/재실행 단계로 병합됩니다.
+- `relativeTransform` (optional, boolean) - `position`, `rotation`, `angle` 값에 대해서 상대값을 이용할 지 결정합니다. 만약, `true` 라면 전달된 값을 객체의 값에 더합니다.
+- `arrayMerge` (optional, string) - 배열 속성을 병합하는 방식을 결정합니다. 기본값은 `'merge'` 입니다.
+  - `'merge'` (기본값): 대상 배열과 소스 배열을 병합합니다.
+  - `'replace'`: 대상 배열을 소스 배열로 완전히 교체하여, 특정 상태로 강제할 때 유용합니다.
+- `refresh` (optional, boolean) - `true`로 설정하면, `changes`의 속성 값이 이전과 동일하더라도 모든 속성 핸들러를 강제로 다시 실행하여 객체를 "새로고침"합니다. 부모의 상태 변화에 따라 자식 객체를 다시 계산해야 할 때 유용합니다. 기본값은 `false` 입니다.
 
 ```js
 // label이 "grid-label-1"인 객체들에 대해 변경 사항 적용
 patchmap.update({
   path: `$..children[?(@.label=="grid-label-1")]`,
   changes: {
-    components: [
-      { type: 'icon', asset: 'wifi' }
-    ]
-  }
+    item: {
+      components: [{ type: 'icon', source: 'wifi' }],
+    },
+  },
 });
 
 // type이 "group"인 객체들에 대해 변경 사항 적용
@@ -251,10 +261,16 @@ patchmap.update({
 patchmap.update({
   path: `$..children[?(@.type=="group")].children[?(@.type=="grid")]`,
   changes: {
-    components: [
-      { type: 'icon', tint: 'black' }
-    ]
-  }
+    item: {
+      components: [{ type: 'icon', tint: 'red' }],
+    },
+  },
+});
+
+// type이 "relations"인 모든 객체를 찾아서(refresh: true로) 강제로 전체 속성 업데이트(새로고침) 수행
+patchmap.update({
+  path: `$..children[?(@.type==="relations")]`,
+  refresh: true
 });
 ```
 

biome.json

@@ -32,7 +32,8 @@
         "noConstructorReturn": "off"
       },
       "complexity": {
-        "noForEach": "off"
+        "noForEach": "off",
+        "noThisInStatic": "off"
       }
     }
   },