panelgrid 0.3.0 → 0.4.0

package/README.md

@@ -133,7 +133,9 @@ export function PanelContent({ id }: { id: PanelId }) {
 
 ### Custom Rearrangement Logic
 
-You can override the default collision resolution logic by providing a custom `rearrangement` function:
+You can override the default collision resolution logic by providing a custom `rearrangement` function.
+
+For advanced use cases, PanelGrid exports [helper functions](./docs/helpers.md) for collision detection, grid calculations, and more. See the [Helper Functions API Reference](./docs/helpers.md) for detailed documentation and examples.
 
 ```tsx
 import { PanelGridProvider, rearrangePanels } from 'panelgrid';
@@ -389,8 +391,25 @@ type RearrangementFunction = (
 
 ### Exported Functions
 
+**Main Export:**
 - `rearrangePanels(movingPanel, allPanels, columnCount)`: Default rearrangement function that can be imported and extended
 
+**Helper Functions:**
+
+PanelGrid exports a comprehensive set of helper functions for building custom rearrangement logic, including collision detection, grid calculations, panel detection, and animation utilities.
+
+See the [Helper Functions API Reference](./docs/helpers.md) for complete documentation.
+
+Quick example:
+```tsx
+import {
+  detectCollisions,
+  hasCollision,
+  snapToGrid,
+  findNewPosition
+} from 'panelgrid/helpers';
+```
+
 ## Development
 
 ```bash

package/dist/helpers/animation.d.cts

@@ -0,0 +1,20 @@
+//#region src/helpers/animation.d.ts
+/**
+ * Options for applying snap-back animation
+ */
+interface ApplySnapAnimationOptions {
+  element: HTMLElement;
+  droppedLeft: number;
+  droppedTop: number;
+  nextLeft: number;
+  nextTop: number;
+  originalTransition: string;
+}
+/**
+ * Applies snap-back animation to element
+ * Smoothly animates the element from its dropped position to the snapped grid position
+ */
+declare function applySnapAnimation(options: ApplySnapAnimationOptions): void;
+//#endregion
+export { applySnapAnimation };
+//# sourceMappingURL=animation.d.cts.map

package/dist/helpers/animation.d.mts

@@ -0,0 +1,20 @@
+//#region src/helpers/animation.d.ts
+/**
+ * Options for applying snap-back animation
+ */
+interface ApplySnapAnimationOptions {
+  element: HTMLElement;
+  droppedLeft: number;
+  droppedTop: number;
+  nextLeft: number;
+  nextTop: number;
+  originalTransition: string;
+}
+/**
+ * Applies snap-back animation to element
+ * Smoothly animates the element from its dropped position to the snapped grid position
+ */
+declare function applySnapAnimation(options: ApplySnapAnimationOptions): void;
+//#endregion
+export { applySnapAnimation };
+//# sourceMappingURL=animation.d.mts.map

package/dist/helpers/gridCalculations.cjs

@@ -60,6 +60,16 @@ function gridPositionToPixels(gridCoord, baseSize, gap) {
 	return Math.max(0, gridCoord * (baseSize + gap));
 }
 /**
+* Snaps a pixel value to the nearest grid position
+* Useful for aligning elements to the grid after drag/resize operations
+*
+* ピクセル値を最も近いグリッド位置にスナップします。
+* ドラッグ・リサイズ操作後に要素をグリッドに整列させる際に利用する。
+*/
+function snapToGrid(pixels, baseSize, gap) {
+	return gridPositionToPixels(pixelsToGridPosition(pixels, baseSize, gap), baseSize, gap);
+}
+/**
 * Gets the maximum Y coordinate of the panels
 * パネルの最大Y座標を取得します。
 */
@@ -73,4 +83,5 @@ exports.gridPositionToPixels = gridPositionToPixels;
 exports.gridToPixels = gridToPixels;
 exports.pixelsToGridPosition = pixelsToGridPosition;
 exports.pixelsToGridSize = pixelsToGridSize;
+exports.snapToGrid = snapToGrid;
 //# sourceMappingURL=gridCalculations.cjs.map

package/dist/helpers/gridCalculations.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"gridCalculations.cjs","names":[],"sources":["../../src/helpers/gridCalculations.ts"],"sourcesContent":["import type { PanelCoordinate } from \"../types\";\n\n/**\n * Converts a pixel value to grid units by dividing by the cell size (baseSize + gap)\n * and rounding up with Math.ceil. Ensures the result is at least 1 and does not exceed available space.\n * When columnCount and xPosition are provided, ensures x + width <= columnCount.\n *\n * ピクセル値をグリッド単位に変換します。セルサイズ (baseSize + gap) で割り、小数点は切り上げて整数にします。\n * 結果は最小1で、columnCountとxPositionが指定された場合はx + width <= columnCountを満たすように制限されます。\n */\nexport function pixelsToGridSize(\n  pixels: number,\n  baseSize: number,\n  gap: number,\n  columnCount?: number,\n  xPosition?: number\n): number {\n  const gridSize = Math.ceil(pixels / (baseSize + gap));\n  const constrainedSize = Math.max(1, gridSize);\n\n  if (columnCount !== undefined && xPosition !== undefined) {\n    // Ensure x + width <= columnCount\n    const maxWidth = Math.max(1, columnCount - xPosition);\n    return Math.min(constrainedSize, maxWidth);\n  }\n\n  if (columnCount !== undefined) {\n    // Legacy behavior: constrain to columnCount\n    return Math.min(constrainedSize, columnCount);\n  }\n\n  return constrainedSize;\n}\n\n/**\n * Converts a pixel coordinate to grid coordinate by dividing by the cell size\n * and rounding down with Math.floor, ensuring the result is not negative and does not cause overflow.\n * When columnCount and width are provided, ensures x + width <= columnCount\n *\n * ピクセル座標をグリッド座標に変換します。セルサイズで割り、小数点は切り捨てて整数にします。\n * 結果が負にならず、columnCountとwidthが指定された場合はx + width <= columnCountを満たすようにします。\n */\nexport function pixelsToGridPosition(\n  pixels: number,\n  baseSize: number,\n  gap: number,\n  columnCount?: number,\n  width?: number\n): number {\n  const gridPosition = Math.max(0, Math.floor(pixels / (baseSize + gap)));\n\n  if (columnCount !== undefined && width !== undefined) {\n    // Ensure x + width <= columnCount\n    const maxPosition = Math.max(0, columnCount - width);\n    return Math.min(gridPosition, maxPosition);\n  }\n\n  if (columnCount !== undefined) {\n    // Legacy behavior: constrain to columnCount - 1\n    return Math.min(gridPosition, columnCount - 1);\n  }\n\n  return gridPosition;\n}\n\n/**\n * Converts grid units to pixels\n * Formula: gridUnits * baseSize + max(0, gridUnits - 1) * gap\n * This accounts for gaps between grid cells but not after the last cell\n *\n * グリッド単位をピクセルに変換します。\n * 計算式: gridUnits * baseSize + max(0, gridUnits - 1) * gap\n * グリッドセル間の gap を考慮しますが、最後のセルの後には gap を含めません。\n */\nexport function gridToPixels(gridUnits: number, baseSize: number, gap: number): number {\n  return gridUnits * baseSize + Math.max(0, gridUnits - 1) * gap;\n}\n\n/**\n * Converts grid coordinate to pixel coordinate for positioning\n * Formula: max(0, gridCoord * (baseSize + gap))\n * This includes the gap after each cell for proper positioning in the grid\n *\n * グリッド座標をピクセル座標に変換します（位置計算用）。\n * 計算式: max(0, gridCoord * (baseSize + gap))\n * 各セルの後に gap を含めて、グリッド内での適切な位置決めを行います。\n */\nexport function gridPositionToPixels(gridCoord: number, baseSize: number, gap: number): number {\n  return Math.max(0, gridCoord * (baseSize + gap));\n}\n\n/**\n * Snaps a pixel value to the nearest grid position\n * Useful for aligning elements to the grid after drag/resize operations\n *\n * ピクセル値を最も近いグリッド位置にスナップします。\n * ドラッグ・リサイズ操作後に要素をグリッドに整列させる際に利用する。\n */\nexport function snapToGrid(pixels: number, baseSize: number, gap: number): number {\n  const gridPosition = pixelsToGridPosition(pixels, baseSize, gap);\n  return gridPositionToPixels(gridPosition, baseSize, gap);\n}\n\n/**\n * Gets the maximum Y coordinate of the panels\n * パネルの最大Y座標を取得します。\n */\nexport function getGridRowCount(panels: PanelCoordinate[]): number {\n  return Math.max(...panels.map((p) => p.y + p.h));\n}\n"],"mappings":";;;;;;;;;;AAUA,SAAgB,iBACd,QACA,UACA,KACA,aACA,WACQ;CACR,MAAM,WAAW,KAAK,KAAK,UAAU,WAAW,KAAK;CACrD,MAAM,kBAAkB,KAAK,IAAI,GAAG,SAAS;AAE7C,KAAI,gBAAgB,UAAa,cAAc,QAAW;EAExD,MAAM,WAAW,KAAK,IAAI,GAAG,cAAc,UAAU;AACrD,SAAO,KAAK,IAAI,iBAAiB,SAAS;;AAG5C,KAAI,gBAAgB,OAElB,QAAO,KAAK,IAAI,iBAAiB,YAAY;AAG/C,QAAO;;;;;;;;;;AAWT,SAAgB,qBACd,QACA,UACA,KACA,aACA,OACQ;CACR,MAAM,eAAe,KAAK,IAAI,GAAG,KAAK,MAAM,UAAU,WAAW,KAAK,CAAC;AAEvE,KAAI,gBAAgB,UAAa,UAAU,QAAW;EAEpD,MAAM,cAAc,KAAK,IAAI,GAAG,cAAc,MAAM;AACpD,SAAO,KAAK,IAAI,cAAc,YAAY;;AAG5C,KAAI,gBAAgB,OAElB,QAAO,KAAK,IAAI,cAAc,cAAc,EAAE;AAGhD,QAAO;;;;;;;;;;;AAYT,SAAgB,aAAa,WAAmB,UAAkB,KAAqB;AACrF,QAAO,YAAY,WAAW,KAAK,IAAI,GAAG,YAAY,EAAE,GAAG;;;;;;;;;;;AAY7D,SAAgB,qBAAqB,WAAmB,UAAkB,KAAqB;AAC7F,QAAO,KAAK,IAAI,GAAG,aAAa,WAAW,KAAK;;;;;;AAmBlD,SAAgB,gBAAgB,QAAmC;AACjE,QAAO,KAAK,IAAI,GAAG,OAAO,KAAK,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC"}
+{"version":3,"file":"gridCalculations.cjs","names":[],"sources":["../../src/helpers/gridCalculations.ts"],"sourcesContent":["import type { PanelCoordinate } from \"../types\";\n\n/**\n * Converts a pixel value to grid units by dividing by the cell size (baseSize + gap)\n * and rounding up with Math.ceil. Ensures the result is at least 1 and does not exceed available space.\n * When columnCount and xPosition are provided, ensures x + width <= columnCount.\n *\n * ピクセル値をグリッド単位に変換します。セルサイズ (baseSize + gap) で割り、小数点は切り上げて整数にします。\n * 結果は最小1で、columnCountとxPositionが指定された場合はx + width <= columnCountを満たすように制限されます。\n */\nexport function pixelsToGridSize(\n  pixels: number,\n  baseSize: number,\n  gap: number,\n  columnCount?: number,\n  xPosition?: number\n): number {\n  const gridSize = Math.ceil(pixels / (baseSize + gap));\n  const constrainedSize = Math.max(1, gridSize);\n\n  if (columnCount !== undefined && xPosition !== undefined) {\n    // Ensure x + width <= columnCount\n    const maxWidth = Math.max(1, columnCount - xPosition);\n    return Math.min(constrainedSize, maxWidth);\n  }\n\n  if (columnCount !== undefined) {\n    // Legacy behavior: constrain to columnCount\n    return Math.min(constrainedSize, columnCount);\n  }\n\n  return constrainedSize;\n}\n\n/**\n * Converts a pixel coordinate to grid coordinate by dividing by the cell size\n * and rounding down with Math.floor, ensuring the result is not negative and does not cause overflow.\n * When columnCount and width are provided, ensures x + width <= columnCount\n *\n * ピクセル座標をグリッド座標に変換します。セルサイズで割り、小数点は切り捨てて整数にします。\n * 結果が負にならず、columnCountとwidthが指定された場合はx + width <= columnCountを満たすようにします。\n */\nexport function pixelsToGridPosition(\n  pixels: number,\n  baseSize: number,\n  gap: number,\n  columnCount?: number,\n  width?: number\n): number {\n  const gridPosition = Math.max(0, Math.floor(pixels / (baseSize + gap)));\n\n  if (columnCount !== undefined && width !== undefined) {\n    // Ensure x + width <= columnCount\n    const maxPosition = Math.max(0, columnCount - width);\n    return Math.min(gridPosition, maxPosition);\n  }\n\n  if (columnCount !== undefined) {\n    // Legacy behavior: constrain to columnCount - 1\n    return Math.min(gridPosition, columnCount - 1);\n  }\n\n  return gridPosition;\n}\n\n/**\n * Converts grid units to pixels\n * Formula: gridUnits * baseSize + max(0, gridUnits - 1) * gap\n * This accounts for gaps between grid cells but not after the last cell\n *\n * グリッド単位をピクセルに変換します。\n * 計算式: gridUnits * baseSize + max(0, gridUnits - 1) * gap\n * グリッドセル間の gap を考慮しますが、最後のセルの後には gap を含めません。\n */\nexport function gridToPixels(gridUnits: number, baseSize: number, gap: number): number {\n  return gridUnits * baseSize + Math.max(0, gridUnits - 1) * gap;\n}\n\n/**\n * Converts grid coordinate to pixel coordinate for positioning\n * Formula: max(0, gridCoord * (baseSize + gap))\n * This includes the gap after each cell for proper positioning in the grid\n *\n * グリッド座標をピクセル座標に変換します（位置計算用）。\n * 計算式: max(0, gridCoord * (baseSize + gap))\n * 各セルの後に gap を含めて、グリッド内での適切な位置決めを行います。\n */\nexport function gridPositionToPixels(gridCoord: number, baseSize: number, gap: number): number {\n  return Math.max(0, gridCoord * (baseSize + gap));\n}\n\n/**\n * Snaps a pixel value to the nearest grid position\n * Useful for aligning elements to the grid after drag/resize operations\n *\n * ピクセル値を最も近いグリッド位置にスナップします。\n * ドラッグ・リサイズ操作後に要素をグリッドに整列させる際に利用する。\n */\nexport function snapToGrid(pixels: number, baseSize: number, gap: number): number {\n  const gridPosition = pixelsToGridPosition(pixels, baseSize, gap);\n  return gridPositionToPixels(gridPosition, baseSize, gap);\n}\n\n/**\n * Gets the maximum Y coordinate of the panels\n * パネルの最大Y座標を取得します。\n */\nexport function getGridRowCount(panels: PanelCoordinate[]): number {\n  return Math.max(...panels.map((p) => p.y + p.h));\n}\n"],"mappings":";;;;;;;;;;AAUA,SAAgB,iBACd,QACA,UACA,KACA,aACA,WACQ;CACR,MAAM,WAAW,KAAK,KAAK,UAAU,WAAW,KAAK;CACrD,MAAM,kBAAkB,KAAK,IAAI,GAAG,SAAS;AAE7C,KAAI,gBAAgB,UAAa,cAAc,QAAW;EAExD,MAAM,WAAW,KAAK,IAAI,GAAG,cAAc,UAAU;AACrD,SAAO,KAAK,IAAI,iBAAiB,SAAS;;AAG5C,KAAI,gBAAgB,OAElB,QAAO,KAAK,IAAI,iBAAiB,YAAY;AAG/C,QAAO;;;;;;;;;;AAWT,SAAgB,qBACd,QACA,UACA,KACA,aACA,OACQ;CACR,MAAM,eAAe,KAAK,IAAI,GAAG,KAAK,MAAM,UAAU,WAAW,KAAK,CAAC;AAEvE,KAAI,gBAAgB,UAAa,UAAU,QAAW;EAEpD,MAAM,cAAc,KAAK,IAAI,GAAG,cAAc,MAAM;AACpD,SAAO,KAAK,IAAI,cAAc,YAAY;;AAG5C,KAAI,gBAAgB,OAElB,QAAO,KAAK,IAAI,cAAc,cAAc,EAAE;AAGhD,QAAO;;;;;;;;;;;AAYT,SAAgB,aAAa,WAAmB,UAAkB,KAAqB;AACrF,QAAO,YAAY,WAAW,KAAK,IAAI,GAAG,YAAY,EAAE,GAAG;;;;;;;;;;;AAY7D,SAAgB,qBAAqB,WAAmB,UAAkB,KAAqB;AAC7F,QAAO,KAAK,IAAI,GAAG,aAAa,WAAW,KAAK;;;;;;;;;AAUlD,SAAgB,WAAW,QAAgB,UAAkB,KAAqB;AAEhF,QAAO,qBADc,qBAAqB,QAAQ,UAAU,IAAI,EACtB,UAAU,IAAI;;;;;;AAO1D,SAAgB,gBAAgB,QAAmC;AACjE,QAAO,KAAK,IAAI,GAAG,OAAO,KAAK,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC"}

package/dist/helpers/gridCalculations.d.cts

@@ -0,0 +1,53 @@
+import "../types.cjs";
+
+//#region src/helpers/gridCalculations.d.ts
+
+/**
+ * Converts a pixel value to grid units by dividing by the cell size (baseSize + gap)
+ * and rounding up with Math.ceil. Ensures the result is at least 1 and does not exceed available space.
+ * When columnCount and xPosition are provided, ensures x + width <= columnCount.
+ *
+ * ピクセル値をグリッド単位に変換します。セルサイズ (baseSize + gap) で割り、小数点は切り上げて整数にします。
+ * 結果は最小1で、columnCountとxPositionが指定された場合はx + width <= columnCountを満たすように制限されます。
+ */
+declare function pixelsToGridSize(pixels: number, baseSize: number, gap: number, columnCount?: number, xPosition?: number): number;
+/**
+ * Converts a pixel coordinate to grid coordinate by dividing by the cell size
+ * and rounding down with Math.floor, ensuring the result is not negative and does not cause overflow.
+ * When columnCount and width are provided, ensures x + width <= columnCount
+ *
+ * ピクセル座標をグリッド座標に変換します。セルサイズで割り、小数点は切り捨てて整数にします。
+ * 結果が負にならず、columnCountとwidthが指定された場合はx + width <= columnCountを満たすようにします。
+ */
+declare function pixelsToGridPosition(pixels: number, baseSize: number, gap: number, columnCount?: number, width?: number): number;
+/**
+ * Converts grid units to pixels
+ * Formula: gridUnits * baseSize + max(0, gridUnits - 1) * gap
+ * This accounts for gaps between grid cells but not after the last cell
+ *
+ * グリッド単位をピクセルに変換します。
+ * 計算式: gridUnits * baseSize + max(0, gridUnits - 1) * gap
+ * グリッドセル間の gap を考慮しますが、最後のセルの後には gap を含めません。
+ */
+declare function gridToPixels(gridUnits: number, baseSize: number, gap: number): number;
+/**
+ * Converts grid coordinate to pixel coordinate for positioning
+ * Formula: max(0, gridCoord * (baseSize + gap))
+ * This includes the gap after each cell for proper positioning in the grid
+ *
+ * グリッド座標をピクセル座標に変換します（位置計算用）。
+ * 計算式: max(0, gridCoord * (baseSize + gap))
+ * 各セルの後に gap を含めて、グリッド内での適切な位置決めを行います。
+ */
+declare function gridPositionToPixels(gridCoord: number, baseSize: number, gap: number): number;
+/**
+ * Snaps a pixel value to the nearest grid position
+ * Useful for aligning elements to the grid after drag/resize operations
+ *
+ * ピクセル値を最も近いグリッド位置にスナップします。
+ * ドラッグ・リサイズ操作後に要素をグリッドに整列させる際に利用する。
+ */
+declare function snapToGrid(pixels: number, baseSize: number, gap: number): number;
+//#endregion
+export { gridPositionToPixels, gridToPixels, pixelsToGridPosition, pixelsToGridSize, snapToGrid };
+//# sourceMappingURL=gridCalculations.d.cts.map

package/dist/helpers/gridCalculations.d.mts

@@ -0,0 +1,53 @@
+import "../types.mjs";
+
+//#region src/helpers/gridCalculations.d.ts
+
+/**
+ * Converts a pixel value to grid units by dividing by the cell size (baseSize + gap)
+ * and rounding up with Math.ceil. Ensures the result is at least 1 and does not exceed available space.
+ * When columnCount and xPosition are provided, ensures x + width <= columnCount.
+ *
+ * ピクセル値をグリッド単位に変換します。セルサイズ (baseSize + gap) で割り、小数点は切り上げて整数にします。
+ * 結果は最小1で、columnCountとxPositionが指定された場合はx + width <= columnCountを満たすように制限されます。
+ */
+declare function pixelsToGridSize(pixels: number, baseSize: number, gap: number, columnCount?: number, xPosition?: number): number;
+/**
+ * Converts a pixel coordinate to grid coordinate by dividing by the cell size
+ * and rounding down with Math.floor, ensuring the result is not negative and does not cause overflow.
+ * When columnCount and width are provided, ensures x + width <= columnCount
+ *
+ * ピクセル座標をグリッド座標に変換します。セルサイズで割り、小数点は切り捨てて整数にします。
+ * 結果が負にならず、columnCountとwidthが指定された場合はx + width <= columnCountを満たすようにします。
+ */
+declare function pixelsToGridPosition(pixels: number, baseSize: number, gap: number, columnCount?: number, width?: number): number;
+/**
+ * Converts grid units to pixels
+ * Formula: gridUnits * baseSize + max(0, gridUnits - 1) * gap
+ * This accounts for gaps between grid cells but not after the last cell
+ *
+ * グリッド単位をピクセルに変換します。
+ * 計算式: gridUnits * baseSize + max(0, gridUnits - 1) * gap
+ * グリッドセル間の gap を考慮しますが、最後のセルの後には gap を含めません。
+ */
+declare function gridToPixels(gridUnits: number, baseSize: number, gap: number): number;
+/**
+ * Converts grid coordinate to pixel coordinate for positioning
+ * Formula: max(0, gridCoord * (baseSize + gap))
+ * This includes the gap after each cell for proper positioning in the grid
+ *
+ * グリッド座標をピクセル座標に変換します（位置計算用）。
+ * 計算式: max(0, gridCoord * (baseSize + gap))
+ * 各セルの後に gap を含めて、グリッド内での適切な位置決めを行います。
+ */
+declare function gridPositionToPixels(gridCoord: number, baseSize: number, gap: number): number;
+/**
+ * Snaps a pixel value to the nearest grid position
+ * Useful for aligning elements to the grid after drag/resize operations
+ *
+ * ピクセル値を最も近いグリッド位置にスナップします。
+ * ドラッグ・リサイズ操作後に要素をグリッドに整列させる際に利用する。
+ */
+declare function snapToGrid(pixels: number, baseSize: number, gap: number): number;
+//#endregion
+export { gridPositionToPixels, gridToPixels, pixelsToGridPosition, pixelsToGridSize, snapToGrid };
+//# sourceMappingURL=gridCalculations.d.mts.map

package/dist/helpers/gridCalculations.mjs

@@ -59,6 +59,16 @@ function gridPositionToPixels(gridCoord, baseSize, gap) {
 	return Math.max(0, gridCoord * (baseSize + gap));
 }
 /**
+* Snaps a pixel value to the nearest grid position
+* Useful for aligning elements to the grid after drag/resize operations
+*
+* ピクセル値を最も近いグリッド位置にスナップします。
+* ドラッグ・リサイズ操作後に要素をグリッドに整列させる際に利用する。
+*/
+function snapToGrid(pixels, baseSize, gap) {
+	return gridPositionToPixels(pixelsToGridPosition(pixels, baseSize, gap), baseSize, gap);
+}
+/**
 * Gets the maximum Y coordinate of the panels
 * パネルの最大Y座標を取得します。
 */
@@ -67,5 +77,5 @@ function getGridRowCount(panels) {
 }
 
 //#endregion
-export { getGridRowCount, gridPositionToPixels, gridToPixels, pixelsToGridPosition, pixelsToGridSize };
+export { getGridRowCount, gridPositionToPixels, gridToPixels, pixelsToGridPosition, pixelsToGridSize, snapToGrid };
 //# sourceMappingURL=gridCalculations.mjs.map

package/dist/helpers/gridCalculations.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"gridCalculations.mjs","names":[],"sources":["../../src/helpers/gridCalculations.ts"],"sourcesContent":["import type { PanelCoordinate } from \"../types\";\n\n/**\n * Converts a pixel value to grid units by dividing by the cell size (baseSize + gap)\n * and rounding up with Math.ceil. Ensures the result is at least 1 and does not exceed available space.\n * When columnCount and xPosition are provided, ensures x + width <= columnCount.\n *\n * ピクセル値をグリッド単位に変換します。セルサイズ (baseSize + gap) で割り、小数点は切り上げて整数にします。\n * 結果は最小1で、columnCountとxPositionが指定された場合はx + width <= columnCountを満たすように制限されます。\n */\nexport function pixelsToGridSize(\n  pixels: number,\n  baseSize: number,\n  gap: number,\n  columnCount?: number,\n  xPosition?: number\n): number {\n  const gridSize = Math.ceil(pixels / (baseSize + gap));\n  const constrainedSize = Math.max(1, gridSize);\n\n  if (columnCount !== undefined && xPosition !== undefined) {\n    // Ensure x + width <= columnCount\n    const maxWidth = Math.max(1, columnCount - xPosition);\n    return Math.min(constrainedSize, maxWidth);\n  }\n\n  if (columnCount !== undefined) {\n    // Legacy behavior: constrain to columnCount\n    return Math.min(constrainedSize, columnCount);\n  }\n\n  return constrainedSize;\n}\n\n/**\n * Converts a pixel coordinate to grid coordinate by dividing by the cell size\n * and rounding down with Math.floor, ensuring the result is not negative and does not cause overflow.\n * When columnCount and width are provided, ensures x + width <= columnCount\n *\n * ピクセル座標をグリッド座標に変換します。セルサイズで割り、小数点は切り捨てて整数にします。\n * 結果が負にならず、columnCountとwidthが指定された場合はx + width <= columnCountを満たすようにします。\n */\nexport function pixelsToGridPosition(\n  pixels: number,\n  baseSize: number,\n  gap: number,\n  columnCount?: number,\n  width?: number\n): number {\n  const gridPosition = Math.max(0, Math.floor(pixels / (baseSize + gap)));\n\n  if (columnCount !== undefined && width !== undefined) {\n    // Ensure x + width <= columnCount\n    const maxPosition = Math.max(0, columnCount - width);\n    return Math.min(gridPosition, maxPosition);\n  }\n\n  if (columnCount !== undefined) {\n    // Legacy behavior: constrain to columnCount - 1\n    return Math.min(gridPosition, columnCount - 1);\n  }\n\n  return gridPosition;\n}\n\n/**\n * Converts grid units to pixels\n * Formula: gridUnits * baseSize + max(0, gridUnits - 1) * gap\n * This accounts for gaps between grid cells but not after the last cell\n *\n * グリッド単位をピクセルに変換します。\n * 計算式: gridUnits * baseSize + max(0, gridUnits - 1) * gap\n * グリッドセル間の gap を考慮しますが、最後のセルの後には gap を含めません。\n */\nexport function gridToPixels(gridUnits: number, baseSize: number, gap: number): number {\n  return gridUnits * baseSize + Math.max(0, gridUnits - 1) * gap;\n}\n\n/**\n * Converts grid coordinate to pixel coordinate for positioning\n * Formula: max(0, gridCoord * (baseSize + gap))\n * This includes the gap after each cell for proper positioning in the grid\n *\n * グリッド座標をピクセル座標に変換します（位置計算用）。\n * 計算式: max(0, gridCoord * (baseSize + gap))\n * 各セルの後に gap を含めて、グリッド内での適切な位置決めを行います。\n */\nexport function gridPositionToPixels(gridCoord: number, baseSize: number, gap: number): number {\n  return Math.max(0, gridCoord * (baseSize + gap));\n}\n\n/**\n * Snaps a pixel value to the nearest grid position\n * Useful for aligning elements to the grid after drag/resize operations\n *\n * ピクセル値を最も近いグリッド位置にスナップします。\n * ドラッグ・リサイズ操作後に要素をグリッドに整列させる際に利用する。\n */\nexport function snapToGrid(pixels: number, baseSize: number, gap: number): number {\n  const gridPosition = pixelsToGridPosition(pixels, baseSize, gap);\n  return gridPositionToPixels(gridPosition, baseSize, gap);\n}\n\n/**\n * Gets the maximum Y coordinate of the panels\n * パネルの最大Y座標を取得します。\n */\nexport function getGridRowCount(panels: PanelCoordinate[]): number {\n  return Math.max(...panels.map((p) => p.y + p.h));\n}\n"],"mappings":";;;;;;;;;AAUA,SAAgB,iBACd,QACA,UACA,KACA,aACA,WACQ;CACR,MAAM,WAAW,KAAK,KAAK,UAAU,WAAW,KAAK;CACrD,MAAM,kBAAkB,KAAK,IAAI,GAAG,SAAS;AAE7C,KAAI,gBAAgB,UAAa,cAAc,QAAW;EAExD,MAAM,WAAW,KAAK,IAAI,GAAG,cAAc,UAAU;AACrD,SAAO,KAAK,IAAI,iBAAiB,SAAS;;AAG5C,KAAI,gBAAgB,OAElB,QAAO,KAAK,IAAI,iBAAiB,YAAY;AAG/C,QAAO;;;;;;;;;;AAWT,SAAgB,qBACd,QACA,UACA,KACA,aACA,OACQ;CACR,MAAM,eAAe,KAAK,IAAI,GAAG,KAAK,MAAM,UAAU,WAAW,KAAK,CAAC;AAEvE,KAAI,gBAAgB,UAAa,UAAU,QAAW;EAEpD,MAAM,cAAc,KAAK,IAAI,GAAG,cAAc,MAAM;AACpD,SAAO,KAAK,IAAI,cAAc,YAAY;;AAG5C,KAAI,gBAAgB,OAElB,QAAO,KAAK,IAAI,cAAc,cAAc,EAAE;AAGhD,QAAO;;;;;;;;;;;AAYT,SAAgB,aAAa,WAAmB,UAAkB,KAAqB;AACrF,QAAO,YAAY,WAAW,KAAK,IAAI,GAAG,YAAY,EAAE,GAAG;;;;;;;;;;;AAY7D,SAAgB,qBAAqB,WAAmB,UAAkB,KAAqB;AAC7F,QAAO,KAAK,IAAI,GAAG,aAAa,WAAW,KAAK;;;;;;AAmBlD,SAAgB,gBAAgB,QAAmC;AACjE,QAAO,KAAK,IAAI,GAAG,OAAO,KAAK,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC"}
+{"version":3,"file":"gridCalculations.mjs","names":[],"sources":["../../src/helpers/gridCalculations.ts"],"sourcesContent":["import type { PanelCoordinate } from \"../types\";\n\n/**\n * Converts a pixel value to grid units by dividing by the cell size (baseSize + gap)\n * and rounding up with Math.ceil. Ensures the result is at least 1 and does not exceed available space.\n * When columnCount and xPosition are provided, ensures x + width <= columnCount.\n *\n * ピクセル値をグリッド単位に変換します。セルサイズ (baseSize + gap) で割り、小数点は切り上げて整数にします。\n * 結果は最小1で、columnCountとxPositionが指定された場合はx + width <= columnCountを満たすように制限されます。\n */\nexport function pixelsToGridSize(\n  pixels: number,\n  baseSize: number,\n  gap: number,\n  columnCount?: number,\n  xPosition?: number\n): number {\n  const gridSize = Math.ceil(pixels / (baseSize + gap));\n  const constrainedSize = Math.max(1, gridSize);\n\n  if (columnCount !== undefined && xPosition !== undefined) {\n    // Ensure x + width <= columnCount\n    const maxWidth = Math.max(1, columnCount - xPosition);\n    return Math.min(constrainedSize, maxWidth);\n  }\n\n  if (columnCount !== undefined) {\n    // Legacy behavior: constrain to columnCount\n    return Math.min(constrainedSize, columnCount);\n  }\n\n  return constrainedSize;\n}\n\n/**\n * Converts a pixel coordinate to grid coordinate by dividing by the cell size\n * and rounding down with Math.floor, ensuring the result is not negative and does not cause overflow.\n * When columnCount and width are provided, ensures x + width <= columnCount\n *\n * ピクセル座標をグリッド座標に変換します。セルサイズで割り、小数点は切り捨てて整数にします。\n * 結果が負にならず、columnCountとwidthが指定された場合はx + width <= columnCountを満たすようにします。\n */\nexport function pixelsToGridPosition(\n  pixels: number,\n  baseSize: number,\n  gap: number,\n  columnCount?: number,\n  width?: number\n): number {\n  const gridPosition = Math.max(0, Math.floor(pixels / (baseSize + gap)));\n\n  if (columnCount !== undefined && width !== undefined) {\n    // Ensure x + width <= columnCount\n    const maxPosition = Math.max(0, columnCount - width);\n    return Math.min(gridPosition, maxPosition);\n  }\n\n  if (columnCount !== undefined) {\n    // Legacy behavior: constrain to columnCount - 1\n    return Math.min(gridPosition, columnCount - 1);\n  }\n\n  return gridPosition;\n}\n\n/**\n * Converts grid units to pixels\n * Formula: gridUnits * baseSize + max(0, gridUnits - 1) * gap\n * This accounts for gaps between grid cells but not after the last cell\n *\n * グリッド単位をピクセルに変換します。\n * 計算式: gridUnits * baseSize + max(0, gridUnits - 1) * gap\n * グリッドセル間の gap を考慮しますが、最後のセルの後には gap を含めません。\n */\nexport function gridToPixels(gridUnits: number, baseSize: number, gap: number): number {\n  return gridUnits * baseSize + Math.max(0, gridUnits - 1) * gap;\n}\n\n/**\n * Converts grid coordinate to pixel coordinate for positioning\n * Formula: max(0, gridCoord * (baseSize + gap))\n * This includes the gap after each cell for proper positioning in the grid\n *\n * グリッド座標をピクセル座標に変換します（位置計算用）。\n * 計算式: max(0, gridCoord * (baseSize + gap))\n * 各セルの後に gap を含めて、グリッド内での適切な位置決めを行います。\n */\nexport function gridPositionToPixels(gridCoord: number, baseSize: number, gap: number): number {\n  return Math.max(0, gridCoord * (baseSize + gap));\n}\n\n/**\n * Snaps a pixel value to the nearest grid position\n * Useful for aligning elements to the grid after drag/resize operations\n *\n * ピクセル値を最も近いグリッド位置にスナップします。\n * ドラッグ・リサイズ操作後に要素をグリッドに整列させる際に利用する。\n */\nexport function snapToGrid(pixels: number, baseSize: number, gap: number): number {\n  const gridPosition = pixelsToGridPosition(pixels, baseSize, gap);\n  return gridPositionToPixels(gridPosition, baseSize, gap);\n}\n\n/**\n * Gets the maximum Y coordinate of the panels\n * パネルの最大Y座標を取得します。\n */\nexport function getGridRowCount(panels: PanelCoordinate[]): number {\n  return Math.max(...panels.map((p) => p.y + p.h));\n}\n"],"mappings":";;;;;;;;;AAUA,SAAgB,iBACd,QACA,UACA,KACA,aACA,WACQ;CACR,MAAM,WAAW,KAAK,KAAK,UAAU,WAAW,KAAK;CACrD,MAAM,kBAAkB,KAAK,IAAI,GAAG,SAAS;AAE7C,KAAI,gBAAgB,UAAa,cAAc,QAAW;EAExD,MAAM,WAAW,KAAK,IAAI,GAAG,cAAc,UAAU;AACrD,SAAO,KAAK,IAAI,iBAAiB,SAAS;;AAG5C,KAAI,gBAAgB,OAElB,QAAO,KAAK,IAAI,iBAAiB,YAAY;AAG/C,QAAO;;;;;;;;;;AAWT,SAAgB,qBACd,QACA,UACA,KACA,aACA,OACQ;CACR,MAAM,eAAe,KAAK,IAAI,GAAG,KAAK,MAAM,UAAU,WAAW,KAAK,CAAC;AAEvE,KAAI,gBAAgB,UAAa,UAAU,QAAW;EAEpD,MAAM,cAAc,KAAK,IAAI,GAAG,cAAc,MAAM;AACpD,SAAO,KAAK,IAAI,cAAc,YAAY;;AAG5C,KAAI,gBAAgB,OAElB,QAAO,KAAK,IAAI,cAAc,cAAc,EAAE;AAGhD,QAAO;;;;;;;;;;;AAYT,SAAgB,aAAa,WAAmB,UAAkB,KAAqB;AACrF,QAAO,YAAY,WAAW,KAAK,IAAI,GAAG,YAAY,EAAE,GAAG;;;;;;;;;;;AAY7D,SAAgB,qBAAqB,WAAmB,UAAkB,KAAqB;AAC7F,QAAO,KAAK,IAAI,GAAG,aAAa,WAAW,KAAK;;;;;;;;;AAUlD,SAAgB,WAAW,QAAgB,UAAkB,KAAqB;AAEhF,QAAO,qBADc,qBAAqB,QAAQ,UAAU,IAAI,EACtB,UAAU,IAAI;;;;;;AAO1D,SAAgB,gBAAgB,QAAmC;AACjE,QAAO,KAAK,IAAI,GAAG,OAAO,KAAK,MAAM,EAAE,IAAI,EAAE,EAAE,CAAC"}

package/dist/helpers/index.cjs

@@ -0,0 +1,17 @@
+const require_rearrangement = require('./rearrangement.cjs');
+const require_animation = require('./animation.cjs');
+const require_gridCalculations = require('./gridCalculations.cjs');
+const require_panelDetection = require('./panelDetection.cjs');
+
+exports.applySnapAnimation = require_animation.applySnapAnimation;
+exports.detectAnimatingPanels = require_panelDetection.detectAnimatingPanels;
+exports.detectCollisions = require_rearrangement.detectCollisions;
+exports.findNewPosition = require_rearrangement.findNewPosition;
+exports.gridPositionToPixels = require_gridCalculations.gridPositionToPixels;
+exports.gridToPixels = require_gridCalculations.gridToPixels;
+exports.hasCollision = require_rearrangement.hasCollision;
+exports.pixelsToGridPosition = require_gridCalculations.pixelsToGridPosition;
+exports.pixelsToGridSize = require_gridCalculations.pixelsToGridSize;
+exports.rearrangePanels = require_rearrangement.rearrangePanels;
+exports.rectanglesOverlap = require_rearrangement.rectanglesOverlap;
+exports.snapToGrid = require_gridCalculations.snapToGrid;

package/dist/helpers/index.d.cts

@@ -0,0 +1,5 @@
+import { applySnapAnimation } from "./animation.cjs";
+import { gridPositionToPixels, gridToPixels, pixelsToGridPosition, pixelsToGridSize, snapToGrid } from "./gridCalculations.cjs";
+import { detectAnimatingPanels } from "./panelDetection.cjs";
+import { detectCollisions, findNewPosition, hasCollision, rearrangePanels, rectanglesOverlap } from "./rearrangement.cjs";
+export { applySnapAnimation, detectAnimatingPanels, detectCollisions, findNewPosition, gridPositionToPixels, gridToPixels, hasCollision, pixelsToGridPosition, pixelsToGridSize, rearrangePanels, rectanglesOverlap, snapToGrid };

package/dist/helpers/index.d.mts

@@ -0,0 +1,5 @@
+import { applySnapAnimation } from "./animation.mjs";
+import { gridPositionToPixels, gridToPixels, pixelsToGridPosition, pixelsToGridSize, snapToGrid } from "./gridCalculations.mjs";
+import { detectAnimatingPanels } from "./panelDetection.mjs";
+import { detectCollisions, findNewPosition, hasCollision, rearrangePanels, rectanglesOverlap } from "./rearrangement.mjs";
+export { applySnapAnimation, detectAnimatingPanels, detectCollisions, findNewPosition, gridPositionToPixels, gridToPixels, hasCollision, pixelsToGridPosition, pixelsToGridSize, rearrangePanels, rectanglesOverlap, snapToGrid };

package/dist/helpers/index.mjs

@@ -0,0 +1,6 @@
+import { detectCollisions, findNewPosition, hasCollision, rearrangePanels, rectanglesOverlap } from "./rearrangement.mjs";
+import { applySnapAnimation } from "./animation.mjs";
+import { gridPositionToPixels, gridToPixels, pixelsToGridPosition, pixelsToGridSize, snapToGrid } from "./gridCalculations.mjs";
+import { detectAnimatingPanels } from "./panelDetection.mjs";
+
+export { applySnapAnimation, detectAnimatingPanels, detectCollisions, findNewPosition, gridPositionToPixels, gridToPixels, hasCollision, pixelsToGridPosition, pixelsToGridSize, rearrangePanels, rectanglesOverlap, snapToGrid };

package/dist/helpers/panelDetection.d.cts

@@ -0,0 +1,20 @@
+import { PanelCoordinate, PanelId } from "../types.cjs";
+
+//#region src/helpers/panelDetection.d.ts
+
+/**
+ * Options for detecting animating panels
+ */
+interface DetectAnimatingPanelsOptions {
+  oldPanels: PanelCoordinate[];
+  newPanels: PanelCoordinate[];
+  excludePanelId: PanelId;
+}
+/**
+ * Detects which panels have changed position/size and marks them for animation
+ * Returns a Set of panel IDs that should be animated
+ */
+declare function detectAnimatingPanels(options: DetectAnimatingPanelsOptions): Set<PanelId>;
+//#endregion
+export { detectAnimatingPanels };
+//# sourceMappingURL=panelDetection.d.cts.map

package/dist/helpers/panelDetection.d.mts

@@ -0,0 +1,20 @@
+import { PanelCoordinate, PanelId } from "../types.mjs";
+
+//#region src/helpers/panelDetection.d.ts
+
+/**
+ * Options for detecting animating panels
+ */
+interface DetectAnimatingPanelsOptions {
+  oldPanels: PanelCoordinate[];
+  newPanels: PanelCoordinate[];
+  excludePanelId: PanelId;
+}
+/**
+ * Detects which panels have changed position/size and marks them for animation
+ * Returns a Set of panel IDs that should be animated
+ */
+declare function detectAnimatingPanels(options: DetectAnimatingPanelsOptions): Set<PanelId>;
+//#endregion
+export { detectAnimatingPanels };
+//# sourceMappingURL=panelDetection.d.mts.map

package/dist/helpers/rearrangement.cjs

@@ -203,6 +203,10 @@ function findNewPositionToAddPanel(panelToAdd, allPanels, columnCount) {
 }
 
 //#endregion
+exports.detectCollisions = detectCollisions;
+exports.findNewPosition = findNewPosition;
 exports.findNewPositionToAddPanel = findNewPositionToAddPanel;
+exports.hasCollision = hasCollision;
 exports.rearrangePanels = rearrangePanels;
+exports.rectanglesOverlap = rectanglesOverlap;
 //# sourceMappingURL=rearrangement.cjs.map

package/dist/helpers/rearrangement.d.cts

@@ -1,7 +1,47 @@
-import { PanelCoordinate } from "../types.cjs";
+import { PanelCoordinate, PanelId } from "../types.cjs";
 
 //#region src/helpers/rearrangement.d.ts
 
+/**
+ * Check if two rectangles overlap using AABB (Axis-Aligned Bounding Box) test
+ * 2つの矩形が重なっているかをAABBテストで判定
+ */
+declare function rectanglesOverlap(a: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}, b: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}): boolean;
+/**
+ * Detect all panels that collide with the given panel
+ * 指定されたパネルと衝突する全てのパネルを検出
+ */
+declare function detectCollisions(panel: PanelCoordinate, panelMap: Map<PanelId, PanelCoordinate>): PanelId[];
+/**
+ * Check if a panel at the given position would collide with any existing panels
+ * 指定された位置にパネルを配置した場合に衝突があるかをチェック
+ */
+declare function hasCollision(candidate: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}, excludeId: PanelId, panelMap: Map<PanelId, PanelCoordinate>): boolean;
+/**
+ * Find a new position for a panel by pushing it away from the colliding panel
+ * Priority: horizontal (right) first, then vertical (down)
+ * 衝突したパネルを押しのける方向に移動させる
+ * 優先順位: 横方向（右）→縦方向（下）
+ */
+declare function findNewPosition(panel: PanelCoordinate, pusher: PanelCoordinate, columnCount: number): {
+  x: number;
+  y: number;
+};
 /**
  * Rearrange panels to resolve collisions when a panel is moved or resized
  * Panels are moved horizontally first, then vertically if needed
@@ -12,5 +52,5 @@ import { PanelCoordinate } from "../types.cjs";
  */
 declare function rearrangePanels(movingPanel: PanelCoordinate, allPanels: PanelCoordinate[], columnCount: number): PanelCoordinate[];
 //#endregion
-export { rearrangePanels };
+export { detectCollisions, findNewPosition, hasCollision, rearrangePanels, rectanglesOverlap };
 //# sourceMappingURL=rearrangement.d.cts.map

package/dist/helpers/rearrangement.d.mts

@@ -1,7 +1,47 @@
-import { PanelCoordinate } from "../types.mjs";
+import { PanelCoordinate, PanelId } from "../types.mjs";
 
 //#region src/helpers/rearrangement.d.ts
 
+/**
+ * Check if two rectangles overlap using AABB (Axis-Aligned Bounding Box) test
+ * 2つの矩形が重なっているかをAABBテストで判定
+ */
+declare function rectanglesOverlap(a: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}, b: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}): boolean;
+/**
+ * Detect all panels that collide with the given panel
+ * 指定されたパネルと衝突する全てのパネルを検出
+ */
+declare function detectCollisions(panel: PanelCoordinate, panelMap: Map<PanelId, PanelCoordinate>): PanelId[];
+/**
+ * Check if a panel at the given position would collide with any existing panels
+ * 指定された位置にパネルを配置した場合に衝突があるかをチェック
+ */
+declare function hasCollision(candidate: {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}, excludeId: PanelId, panelMap: Map<PanelId, PanelCoordinate>): boolean;
+/**
+ * Find a new position for a panel by pushing it away from the colliding panel
+ * Priority: horizontal (right) first, then vertical (down)
+ * 衝突したパネルを押しのける方向に移動させる
+ * 優先順位: 横方向（右）→縦方向（下）
+ */
+declare function findNewPosition(panel: PanelCoordinate, pusher: PanelCoordinate, columnCount: number): {
+  x: number;
+  y: number;
+};
 /**
  * Rearrange panels to resolve collisions when a panel is moved or resized
  * Panels are moved horizontally first, then vertically if needed
@@ -12,5 +52,5 @@ import { PanelCoordinate } from "../types.mjs";
  */
 declare function rearrangePanels(movingPanel: PanelCoordinate, allPanels: PanelCoordinate[], columnCount: number): PanelCoordinate[];
 //#endregion
-export { rearrangePanels };
+export { detectCollisions, findNewPosition, hasCollision, rearrangePanels, rectanglesOverlap };
 //# sourceMappingURL=rearrangement.d.mts.map

package/dist/helpers/rearrangement.mjs

@@ -202,5 +202,5 @@ function findNewPositionToAddPanel(panelToAdd, allPanels, columnCount) {
 }
 
 //#endregion
-export { findNewPositionToAddPanel, rearrangePanels };
+export { detectCollisions, findNewPosition, findNewPositionToAddPanel, hasCollision, rearrangePanels, rectanglesOverlap };
 //# sourceMappingURL=rearrangement.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "panelgrid",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A flexible and performant React grid layout library with drag-and-drop and resize capabilities",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -19,6 +19,16 @@
       },
       "default": "./dist/index.mjs"
     },
+    "./helpers": {
+      "import": {
+        "types": "./dist/helpers/index.d.mts",
+        "default": "./dist/helpers/index.mjs"
+      },
+      "require": {
+        "types": "./dist/helpers/index.d.cts",
+        "default": "./dist/helpers/index.cjs"
+      }
+    },
     "./styles.css": "./dist/styles.css",
     "./package.json": "./package.json"
   },
@@ -62,7 +72,12 @@
     "typecheck": "tsc -b --noEmit",
     "preview": "vite preview",
     "test": "vitest",
-    "prepublishOnly": "yarn test run && yarn typecheck && yarn lint && yarn build"
+    "prepublishOnly": "yarn test run && yarn typecheck && yarn lint && yarn build",
+    "release": "commit-and-tag-version",
+    "release:patch": "commit-and-tag-version --release-as patch",
+    "release:minor": "commit-and-tag-version --release-as minor",
+    "release:major": "commit-and-tag-version --release-as major",
+    "release:dry-run": "commit-and-tag-version --dry-run"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx}": [
@@ -86,6 +101,7 @@
     "@types/react": "^19.1.16",
     "@types/react-dom": "^19.1.9",
     "@vitejs/plugin-react-swc": "^4.1.0",
+    "commit-and-tag-version": "^12.6.1",
     "husky": "^9.1.7",
     "jsdom": "^27.0.1",
     "lint-staged": "^16.2.6",