@simplysm/core-browser 13.0.68 → 13.0.70

package/src/extensions/element-ext.ts

@@ -2,82 +2,82 @@ import { isFocusable } from "tabbable";
 import { TimeoutError } from "@simplysm/core-common";
 
 /**
- * 요소 bounds 정보 타입
+ * Element bounds information type
  */
 export interface ElementBounds {
-  /** 측정 대상 요소 */
+  /** Element to be measured */
   target: Element;
-  /** 뷰포트 기준 상단 위치 */
+  /** Top position relative to viewport */
   top: number;
-  /** 뷰포트 기준 왼쪽 위치 */
+  /** Left position relative to viewport */
   left: number;
-  /** 요소 너비 */
+  /** Element width */
   width: number;
-  /** 요소 높이 */
+  /** Element height */
   height: number;
 }
 
 declare global {
   interface Element {
     /**
-     * 셀렉터로 하위 요소 전체 검색
+     * Find all child elements matching selector
      *
-     * @param selector - CSS 셀렉터
-     * @returns 매칭된 요소 배열 (빈 셀렉터는 빈 배열 반환)
+     * @param selector - CSS selector
+     * @returns Array of matching elements (empty selector returns empty array)
      */
     findAll<T extends Element = Element>(selector: string): T[];
 
     /**
-     * 셀렉터로 첫 번째 매칭 요소 검색
+     * Find first element matching selector
      *
-     * @param selector - CSS 셀렉터
-     * @returns 첫 번째 매칭 요소 또는 undefined (빈 셀렉터는 undefined 반환)
+     * @param selector - CSS selector
+     * @returns First matching element or undefined (empty selector returns undefined)
      */
     findFirst<T extends Element = Element>(selector: string): T | undefined;
 
     /**
-     * 요소를 첫 번째 자식으로 삽입
+     * Insert element as first child
      *
-     * @param child - 삽입할 자식 요소
-     * @returns 삽입된 자식 요소
+     * @param child - Child element to insert
+     * @returns Inserted child element
      */
     prependChild<T extends Element>(child: T): T;
 
     /**
-     * 모든 부모 요소 목록 반환 (가까운 순서)
+     * Get all parent elements (in order of proximity)
      *
-     * @returns 부모 요소 배열 (가까운 부모부터 순서대로)
+     * @returns Array of parent elements (from closest to farthest)
      */
     getParents(): Element[];
 
     /**
-     * 부모 중 첫 번째 포커스 가능 요소 검색 (tabbable 사용)
+     * Find first focusable parent element (using tabbable)
      *
-     * @returns 포커스 가능한 첫 번째 부모 요소 또는 undefined
+     * @returns First focusable parent element or undefined
      */
     findFocusableParent(): HTMLElement | undefined;
 
     /**
-     * 자식 중 첫 번째 포커스 가능 요소 검색 (tabbable 사용)
+     * Find first focusable child element (using tabbable)
      *
-     * @returns 포커스 가능한 첫 번째 자식 요소 또는 undefined
+     * @returns First focusable child element or undefined
      */
     findFirstFocusableChild(): HTMLElement | undefined;
 
     /**
-     * 요소가 offset 기준 요소인지 확인 (position: relative/absolute/fixed/sticky)
+     * Check if element is an offset parent (position: relative/absolute/fixed/sticky)
      *
-     * @returns position 속성이 relative, absolute, fixed, sticky 중 하나면 true
+     * @returns true if position property is one of relative, absolute, fixed, or sticky
      */
     isOffsetElement(): boolean;
 
     /**
-     * 요소가 화면에 보이는지 확인
+     * Check if element is visible on screen
      *
      * @remarks
-     * clientRects 존재 여부, visibility: hidden, opacity: 0 여부를 확인한다.
+     * Checks existence of clientRects, visibility: hidden, and opacity: 0.
      *
-     * @returns 요소가 화면에 보이면 true
+     * @returns true if element is visible on screen
      */
     isVisible(): boolean;
   }
@@ -144,13 +144,13 @@ Element.prototype.isVisible = function (): boolean {
 };
 
 // ============================================================================
-// 정적 함수 (이벤트 핸들러용 또는 여러 요소 대상)
+// Static functions (for event handlers or multiple elements)
 // ============================================================================
 
 /**
- * 요소 내용을 클립보드에 복사 (copy 이벤트 핸들러에서 사용)
+ * Copy element content to clipboard (use with copy event handler)
  *
- * @param event - copy 이벤트 객체
+ * @param event - copy event object
  */
 export function copyElement(event: ClipboardEvent): void {
   const clipboardData = event.clipboardData;
@@ -167,13 +167,13 @@ export function copyElement(event: ClipboardEvent): void {
 }
 
 /**
- * 클립보드 내용을 요소에 붙여넣기 (paste 이벤트 핸들러에서 사용)
+ * Paste clipboard content to element (use with paste event handler)
  *
  * @remarks
- * 대상 요소 내의 첫 번째 input/textarea를 찾아 전체 값을 클립보드 내용으로 교체한다.
- * 커서 위치나 선택 영역을 고려하지 않는다.
+ * Finds the first input/textarea within the target element and replaces its entire value with clipboard content.
+ * Does not consider cursor position or selection.
  *
- * @param event - paste 이벤트 객체
+ * @param event - paste event object
  */
 export function pasteToElement(event: ClipboardEvent): void {
   const clipboardData = event.clipboardData;
@@ -191,20 +191,20 @@ export function pasteToElement(event: ClipboardEvent): void {
 }
 
 /**
- * IntersectionObserver를 사용하여 요소들의 bounds 정보 조회
+ * Get bounds information for elements using IntersectionObserver
  *
- * @param els - 대상 요소 배열
- * @param timeout - 타임아웃 (밀리초, 기본: 5000)
- * @throws {TimeoutError} 타임아웃 시간 내에 응답이 없을 경우
+ * @param els - Array of target elements
+ * @param timeout - Timeout in milliseconds (default: 5000)
+ * @throws {TimeoutError} If no response within timeout duration
  */
 export async function getBounds(els: Element[], timeout: number = 5000): Promise<ElementBounds[]> {
-  // 중복 제거 및 입력 순서대로 결과를 정렬하기 위한 인덱스 맵
+  // Index map to remove duplicates and sort results in input order
   const indexMap = new Map(els.map((el, i) => [el, i] as const));
   if (indexMap.size === 0) {
     return [];
   }
 
-  // 정렬 성능 최적화를 위한 인덱스 맵
+  // Index map for sorting performance optimization
   const sortIndexMap = new Map(els.map((el, i) => [el, i] as const));
 
   let observer: IntersectionObserver | undefined;
@@ -231,7 +231,7 @@ export async function getBounds(els: Element[], timeout: number = 5000): Promise
 
           if (indexMap.size === 0) {
             observer?.disconnect();
-            // 입력 순서대로 정렬
+            // Sort in input order
             resolve(
               results.sort((a, b) => sortIndexMap.get(a.target)! - sortIndexMap.get(b.target)!),
             );
@@ -243,7 +243,7 @@ export async function getBounds(els: Element[], timeout: number = 5000): Promise
         }
       }),
       new Promise<ElementBounds[]>((_, reject) =>
-        setTimeout(() => reject(new TimeoutError(undefined, `${timeout}ms 초과`)), timeout),
+        setTimeout(() => reject(new TimeoutError(undefined, `${timeout}ms timeout`)), timeout),
       ),
     ]);
   } finally {

package/src/extensions/html-element-ext.ts

@@ -3,44 +3,44 @@ import { ArgumentError } from "@simplysm/core-common";
 declare global {
   interface HTMLElement {
     /**
-     * 강제 리페인트 (reflow 트리거)
+     * Force repaint (triggers reflow)
      */
     repaint(): void;
 
     /**
-     * 부모 요소 기준 상대 위치 계산 (CSS 포지셔닝용)
+     * Calculate relative position based on parent element (for CSS positioning)
      *
      * @remarks
-     * 이 함수는 요소의 위치를 부모 요소 기준으로 계산하되, `window.scrollX/Y`를 포함하여
-     * CSS `top`/`left` 속성에 직접 사용할 수 있는 문서 기준 좌표를 반환한다.
+     * Calculates element position relative to parent element, returning document-based coordinates
+     * including `window.scrollX/Y` that can be directly used in CSS `top`/`left` properties.
      *
-     * 주요 사용 사례:
-     * - 드롭다운, 팝업 등을 `document.body`에 append 후 위치 지정
-     * - 스크롤된 페이지에서도 올바르게 동작
+     * Common use cases:
+     * - Position dropdowns, popups after appending to `document.body`
+     * - Works correctly on scrolled pages
      *
-     * 계산에 포함되는 요소:
-     * - 뷰포트 기준 위치 (getBoundingClientRect)
-     * - 문서 스크롤 위치 (window.scrollX/Y)
-     * - 부모 요소 내부 스크롤 (parentEl.scrollTop/Left)
-     * - 중간 요소들의 border 두께
-     * - CSS transform 변환
+     * Factors included in calculation:
+     * - Viewport-relative position (getBoundingClientRect)
+     * - Document scroll position (window.scrollX/Y)
+     * - Parent element internal scroll (parentEl.scrollTop/Left)
+     * - Border thickness of intermediate elements
+     * - CSS transform transformations
      *
-     * @param parent - 기준이 될 부모 요소 또는 셀렉터 (예: document.body, ".container")
-     * @returns CSS top/left 속성에 사용할 수 있는 좌표
-     * @throws {ArgumentError} 부모 요소를 찾을 수 없는 경우
+     * @param parent - Parent element or selector to use as reference (e.g., document.body, ".container")
+     * @returns Coordinates usable in CSS top/left properties
+     * @throws {ArgumentError} If parent element cannot be found
      */
     getRelativeOffset(parent: HTMLElement | string): { top: number; left: number };
 
     /**
-     * 대상이 offset 영역(고정 헤더/고정 열 등)에 가려진 경우, 보이도록 스크롤
+     * Scroll to make target visible if hidden by offset area (e.g., fixed header/column)
      *
      * @remarks
-     * 이 함수는 대상이 스크롤 영역의 위쪽/왼쪽 경계를 벗어난 경우만 처리한다.
-     * 아래쪽/오른쪽으로 스크롤이 필요한 경우는 브라우저의 기본 포커스 스크롤 동작에 의존한다.
-     * 주로 고정 헤더나 고정 열이 있는 테이블에서 포커스 이벤트와 함께 사용된다.
+     * Only handles cases where target extends beyond top/left boundaries of scroll area.
+     * For scrolling needed downward/rightward, relies on browser's default focus scroll behavior.
+     * Typically used with focus events on tables with fixed headers or columns.
      *
-     * @param target - 대상의 컨테이너 내 위치 (offsetTop, offsetLeft)
-     * @param offset - 가려지면 안 되는 영역 크기 (예: 고정 헤더 높이, 고정 열 너비)
+     * @param target - Target position within container (offsetTop, offsetLeft)
+     * @param offset - Size of area that must not be obscured (e.g., fixed header height, fixed column width)
      */
     scrollIntoViewIfNeeded(
       target: { top: number; left: number },
@@ -50,8 +50,8 @@ declare global {
 }
 
 HTMLElement.prototype.repaint = function (): void {
-  // offsetHeight 접근 시 브라우저는 동기적 레이아웃 계산(forced synchronous layout)을 수행하며,
-  // 이로 인해 현재 배치된 스타일 변경사항이 즉시 적용되어 리페인트가 트리거된다.
+  // Accessing offsetHeight triggers forced synchronous layout in browser,
+  // causing style changes in current layout to be applied immediately and triggering repaint.
   void this.offsetHeight;
 };
 

package/src/index.ts

@@ -1,4 +1,4 @@
-// core-browser: 브라우저 전용 유틸리티
+// core-browser: Browser-only utilities
 
 // extensions (side-effect)
 import "./extensions/element-ext";

package/src/utils/download.ts

@@ -1,8 +1,8 @@
 /**
- * Blob을 파일로 다운로드
+ * Download Blob as file
  *
- * @param blob - 다운로드할 Blob 객체
- * @param fileName - 저장될 파일 이름
+ * @param blob - Blob object to download
+ * @param fileName - File name to save as
  */
 export function downloadBlob(blob: Blob, fileName: string): void {
   const url = URL.createObjectURL(blob);

package/src/utils/fetch.ts

@@ -4,7 +4,7 @@ export interface DownloadProgress {
 }
 
 /**
- * URL에서 바이너리 데이터 다운로드 (진행률 콜백 지원)
+ * Download binary data from URL (with progress callback support)
  */
 export async function fetchUrlBytes(
   url: string,
@@ -22,7 +22,7 @@ export async function fetchUrlBytes(
   }
 
   try {
-    // Content-Length를 알 수 있으면 미리 할당하여 메모리 효율성 향상
+    // If Content-Length is known, pre-allocate for memory efficiency
     if (contentLength > 0) {
       const result = new Uint8Array(contentLength);
       let receivedLength = 0;
@@ -39,7 +39,7 @@ export async function fetchUrlBytes(
       return result;
     }
 
-    // Content-Length를 모르면 청크 수집 후 병합 (chunked encoding)
+    // If Content-Length is unknown, collect chunks then merge (chunked encoding)
     const chunks: Uint8Array[] = [];
     let receivedLength = 0;
 
@@ -51,7 +51,7 @@ export async function fetchUrlBytes(
       receivedLength += value.length;
     }
 
-    // 청크 병합
+    // Merge chunks
     const result = new Uint8Array(receivedLength);
     let position = 0;
     for (const chunk of chunks) {

package/src/utils/file-dialog.ts

@@ -1,5 +1,5 @@
 /**
- * 파일 선택 다이얼로그를 프로그래밍 방식으로 열기
+ * Programmatically open file selection dialog
  */
 export function openFileDialog(options?: {
   accept?: string;