@simplysm/core-browser 13.0.100 → 14.0.1

package/dist/utils/file-dialog.js

@@ -1,21 +1,21 @@
-function openFileDialog(options) {
-  return new Promise((resolve) => {
-    const input = document.createElement("input");
-    input.type = "file";
-    input.multiple = (options == null ? void 0 : options.multiple) ?? false;
-    if ((options == null ? void 0 : options.accept) != null) {
-      input.accept = options.accept;
-    }
-    input.onchange = () => {
-      resolve(input.files != null && input.files.length > 0 ? [...input.files] : void 0);
-    };
-    input.addEventListener("cancel", () => {
-      resolve(void 0);
+/**
+ * 프로그래밍 방식으로 파일 선택 대화상자 열기
+ */
+export function openFileDialog(options) {
+    return new Promise((resolve) => {
+        const input = document.createElement("input");
+        input.type = "file";
+        input.multiple = options?.multiple ?? false;
+        if (options?.accept != null) {
+            input.accept = options.accept;
+        }
+        input.onchange = () => {
+            resolve(input.files != null && input.files.length > 0 ? [...input.files] : undefined);
+        };
+        input.addEventListener("cancel", () => {
+            resolve(undefined);
+        });
+        input.click();
     });
-    input.click();
-  });
 }
-export {
-  openFileDialog
-};
-//# sourceMappingURL=file-dialog.js.map
+//# sourceMappingURL=file-dialog.js.map

package/dist/utils/file-dialog.js.map

@@ -1,6 +1 @@
-{
-  "version": 3,
-  "sources": ["../../src/utils/file-dialog.ts"],
-  "mappings": "AAGO,SAAS,eAAe,SAGC;AAC9B,SAAO,IAAI,QAAQ,CAAC,YAAY;AAC9B,UAAM,QAAQ,SAAS,cAAc,OAAO;AAC5C,UAAM,OAAO;AACb,UAAM,YAAW,mCAAS,aAAY;AACtC,SAAI,mCAAS,WAAU,MAAM;AAC3B,YAAM,SAAS,QAAQ;AAAA,IACzB;AACA,UAAM,WAAW,MAAM;AACrB,cAAQ,MAAM,SAAS,QAAQ,MAAM,MAAM,SAAS,IAAI,CAAC,GAAG,MAAM,KAAK,IAAI,MAAS;AAAA,IACtF;AACA,UAAM,iBAAiB,UAAU,MAAM;AACrC,cAAQ,MAAS;AAAA,IACnB,CAAC;AACD,UAAM,MAAM;AAAA,EACd,CAAC;AACH;",
-  "names": []
-}
+{"version":3,"file":"file-dialog.js","sourceRoot":"","sources":["..\\..\\src\\utils\\file-dialog.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,OAG9B;IACC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,KAAK,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;QAC9C,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC;QACpB,KAAK,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,KAAK,CAAC;QAC5C,IAAI,OAAO,EAAE,MAAM,IAAI,IAAI,EAAE,CAAC;YAC5B,KAAK,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAChC,CAAC;QACD,KAAK,CAAC,QAAQ,GAAG,GAAG,EAAE;YACpB,OAAO,CAAC,KAAK,CAAC,KAAK,IAAI,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACxF,CAAC,CAAC;QACF,KAAK,CAAC,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE;YACpC,OAAO,CAAC,SAAS,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,KAAK,CAAC,KAAK,EAAE,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@simplysm/core-browser",
-  "version": "13.0.100",
-  "description": "Simplysm package - Core module (browser)",
-  "author": "simplysm",
+  "version": "14.0.1",
+  "description": "심플리즘 패키지 - 코어 (browser)",
+  "author": "심플리즘",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -14,19 +14,16 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "docs",
-    "src",
-    "tests"
+    "src"
   ],
   "sideEffects": [
+    "./src/extensions/element-ext.ts",
+    "./src/extensions/html-element-ext.ts",
     "./dist/extensions/element-ext.js",
     "./dist/extensions/html-element-ext.js"
   ],
   "dependencies": {
     "tabbable": "^6.4.0",
-    "@simplysm/core-common": "13.0.100"
-  },
-  "devDependencies": {
-    "happy-dom": "^20.8.4"
+    "@simplysm/core-common": "14.0.1"
   }
 }

package/src/extensions/element-ext.ts

@@ -2,82 +2,82 @@ import { isFocusable } from "tabbable";
 import { TimeoutError } from "@simplysm/core-common";
 
 /**
- * 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 selector
-     * @returns Array of matching elements (empty selector returns empty array)
+     * @param selector - CSS 선택자
+     * @returns 일치하는 요소 배열 (빈 선택자는 빈 배열 반환)
      */
     findAll<TEl extends Element = Element>(selector: string): TEl[];
 
     /**
-     * Find first element matching selector
+     * 선택자와 일치하는 첫 번째 요소 검색
      *
-     * @param selector - CSS selector
-     * @returns First matching element or undefined (empty selector returns undefined)
+     * @param selector - CSS 선택자
+     * @returns 첫 번째 일치 요소 또는 undefined (빈 선택자는 undefined 반환)
      */
     findFirst<TEl extends Element = Element>(selector: string): TEl | undefined;
 
     /**
-     * Insert element as first child
+     * 요소를 첫 번째 자식으로 삽입
      *
-     * @param child - Child element to insert
-     * @returns Inserted child element
+     * @param child - 삽입할 자식 요소
+     * @returns 삽입된 자식 요소
      */
     prependChild<TEl extends Element>(child: TEl): TEl;
 
     /**
-     * Get all parent elements (in order of proximity)
+     * 모든 부모 요소 조회 (가까운 순서)
      *
-     * @returns Array of parent elements (from closest to farthest)
+     * @returns 부모 요소 배열 (가장 가까운 것부터 먼 것 순)
      */
     getParents(): Element[];
 
     /**
-     * Find first focusable parent element (using tabbable)
+     * 첫 번째 포커스 가능한 부모 요소 검색 (tabbable 사용)
      *
-     * @returns First focusable parent element or undefined
+     * @returns 첫 번째 포커스 가능한 부모 요소 또는 undefined
      */
     findFocusableParent(): HTMLElement | undefined;
 
     /**
-     * Find first focusable child element (using tabbable)
+     * 첫 번째 포커스 가능한 자식 요소 검색 (tabbable 사용)
      *
-     * @returns First focusable child element or undefined
+     * @returns 첫 번째 포커스 가능한 자식 요소 또는 undefined
      */
     findFirstFocusableChild(): HTMLElement | undefined;
 
     /**
-     * Check if element is an offset parent (position: relative/absolute/fixed/sticky)
+     * 요소가 offset parent인지 확인 (position: relative/absolute/fixed/sticky)
      *
-     * @returns true if position property is one of relative, absolute, fixed, or sticky
+     * @returns position 속성이 relative, absolute, fixed, sticky 중 하나이면 true
      */
     isOffsetElement(): boolean;
 
     /**
-     * Check if element is visible on screen
+     * 요소가 화면에 보이는지 확인
      *
      * @remarks
-     * Checks existence of clientRects, visibility: hidden, and opacity: 0.
+     * clientRects 존재 여부, visibility: hidden, opacity: 0을 확인합니다.
      *
-     * @returns true if element is visible on screen
+     * @returns 요소가 화면에 보이면 true
      */
     isVisible(): boolean;
   }
@@ -144,13 +144,13 @@ Element.prototype.isVisible = function (): boolean {
 };
 
 // ============================================================================
-// Static functions (for event handlers or multiple elements)
+// 정적 함수 (이벤트 핸들러 또는 다중 요소용)
 // ============================================================================
 
 /**
- * Copy element content to clipboard (use with copy event handler)
+ * 요소 내용을 클립보드에 복사 (copy 이벤트 핸들러와 함께 사용)
  *
- * @param event - copy event object
+ * @param event - copy 이벤트 객체
  */
 export function copyElement(event: ClipboardEvent): void {
   const clipboardData = event.clipboardData;
@@ -167,13 +167,13 @@ export function copyElement(event: ClipboardEvent): void {
 }
 
 /**
- * Paste clipboard content to element (use with paste event handler)
+ * 클립보드 내용을 요소에 붙여넣기 (paste 이벤트 핸들러와 함께 사용)
  *
  * @remarks
- * Finds the first input/textarea within the target element and replaces its entire value with clipboard content.
- * Does not consider cursor position or selection.
+ * 대상 요소 내의 첫 번째 input/textarea를 찾아 전체 값을 클립보드 내용으로 교체합니다.
+ * 커서 위치나 선택 영역은 고려하지 않습니다.
  *
- * @param event - paste event object
+ * @param event - paste 이벤트 객체
  */
 export function pasteToElement(event: ClipboardEvent): void {
   const clipboardData = event.clipboardData;
@@ -191,20 +191,20 @@ export function pasteToElement(event: ClipboardEvent): void {
 }
 
 /**
- * Get bounds information for elements using IntersectionObserver
+ * IntersectionObserver를 사용하여 요소의 경계 정보 조회
  *
- * @param els - Array of target elements
- * @param timeout - Timeout in milliseconds (default: 5000)
- * @throws {TimeoutError} If no response within timeout duration
+ * @param els - 대상 요소 배열
+ * @param timeout - 타임아웃 밀리초 (기본값: 5000)
+ * @throws {TimeoutError} 타임아웃 시간 내에 응답이 없는 경우
  */
 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 [];
   }
 
-  // Set to track remaining elements
+  // 남은 요소를 추적하기 위한 Set
   const remaining = new Set(indexMap.keys());
 
   let observer: IntersectionObserver | undefined;
@@ -231,7 +231,7 @@ export async function getBounds(els: Element[], timeout: number = 5000): Promise
 
           if (remaining.size === 0) {
             observer?.disconnect();
-            // Sort in input order
+            // 입력 순서대로 정렬
             resolve(
               results.sort((a, b) => indexMap.get(a.target)! - indexMap.get(b.target)!),
             );

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

@@ -3,44 +3,44 @@ import { ArgumentError } from "@simplysm/core-common";
 declare global {
   interface HTMLElement {
     /**
-     * Force repaint (triggers reflow)
+     * 강제 리페인트 (reflow 트리거)
      */
     repaint(): void;
 
     /**
-     * Calculate relative position based on parent element (for CSS positioning)
+     * 부모 요소 기준 상대 위치 계산 (CSS 포지셔닝용)
      *
      * @remarks
-     * 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.
+     * 부모 요소 기준으로 요소 위치를 계산하며, CSS `top`/`left` 속성에 바로 사용할 수 있는
+     * `window.scrollX/Y`를 포함한 문서 기반 좌표를 반환합니다.
      *
-     * Common use cases:
-     * - Position dropdowns, popups after appending to `document.body`
-     * - Works correctly on scrolled pages
+     * 주요 사용 사례:
+     * - `document.body`에 append한 후 드롭다운, 팝업 위치 지정
+     * - 스크롤된 페이지에서도 정상 동작
      *
-     * 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
+     * 계산에 포함되는 요소:
+     * - 뷰포트 기준 위치 (getBoundingClientRect)
+     * - 문서 스크롤 위치 (window.scrollX/Y)
+     * - 부모 요소 내부 스크롤 (parentEl.scrollTop/Left)
+     * - 중간 요소의 border 두께
+     * - CSS transform 변환
      *
-     * @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
+     * @param parent - 기준이 되는 부모 요소 또는 선택자 (예: document.body, ".container")
+     * @returns CSS top/left 속성에 사용 가능한 좌표
+     * @throws {ArgumentError} 부모 요소를 찾을 수 없는 경우
      */
     getRelativeOffset(parent: HTMLElement | string): { top: number; left: number };
 
     /**
-     * Scroll to make target visible if hidden by offset area (e.g., fixed header/column)
+     * offset 영역(예: 고정 헤더/컬럼)에 가려진 경우 대상이 보이도록 스크롤
      *
      * @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 - Target position within container (offsetTop, offsetLeft)
-     * @param offset - Size of area that must not be obscured (e.g., fixed header height, fixed column width)
+     * @param target - 컨테이너 내 대상 위치 (offsetTop, offsetLeft)
+     * @param offset - 가려지면 안 되는 영역의 크기 (예: 고정 헤더 높이, 고정 컬럼 너비)
      */
     scrollIntoViewIfNeeded(
       target: { top: number; left: number },
@@ -50,8 +50,8 @@ declare global {
 }
 
 HTMLElement.prototype.repaint = function (): void {
-  // Accessing offsetHeight triggers forced synchronous layout in browser,
-  // causing style changes in current layout to be applied immediately and triggering repaint.
+  // offsetHeight에 접근하면 브라우저에서 강제 동기 레이아웃이 트리거되어,
+  // 현재 레이아웃의 스타일 변경이 즉시 적용되고 리페인트가 발생합니다.
   void this.offsetHeight;
 };
 

package/src/index.ts

@@ -1,10 +1,10 @@
-// core-browser: Browser-only utilities
+// core-browser: 브라우저 전용 유틸리티
 
-// extensions (side-effect)
+// 확장 (사이드 이펙트)
 import "./extensions/element-ext";
 import "./extensions/html-element-ext";
 
-// re-exports
+// 재내보내기
 export * from "./extensions/element-ext";
 export * from "./extensions/html-element-ext";
 export * from "./utils/download";

package/src/utils/IndexedDbStore.ts

@@ -53,7 +53,7 @@ export class IndexedDbStore {
       };
       req.onblocked = () => {
         this._opening = undefined;
-        reject(new Error("Database blocked by another connection"));
+        reject(new Error("다른 연결에 의해 데이터베이스가 차단되었습니다"));
       };
     });
 
@@ -69,7 +69,7 @@ export class IndexedDbStore {
     const tx = db.transaction(storeName, mode);
     const store = tx.objectStore(storeName);
 
-    // Await fn result first
+    // 먼저 fn 결과를 대기
     let result: TResult;
     let fnError: unknown;
     let hasFnError = false;
@@ -81,7 +81,7 @@ export class IndexedDbStore {
       tx.abort();
     }
 
-    // Wait for transaction completion
+    // 트랜잭션 완료 대기
     return new Promise<TResult>((resolve, reject) => {
       if (hasFnError) {
         tx.onabort = () => {

package/src/utils/download.ts

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

package/src/utils/fetch.ts

@@ -6,7 +6,7 @@ export interface DownloadProgress {
 }
 
 /**
- * Download binary data from URL (with progress callback support)
+ * URL에서 바이너리 데이터 다운로드 (진행 콜백 지원)
  */
 export async function fetchUrlBytes(
   url: string,
@@ -14,17 +14,17 @@ export async function fetchUrlBytes(
 ): Promise<Uint8Array> {
   const response = await fetch(url);
   if (!response.ok) {
-    throw new Error(`Download failed: ${response.status} ${response.statusText}`);
+    throw new Error(`다운로드 실패: ${response.status} ${response.statusText}`);
   }
 
   const contentLength = Number(response.headers.get("Content-Length") ?? 0);
   const reader = response.body?.getReader();
   if (!reader) {
-    throw new Error("Response body is not readable");
+    throw new Error("응답 본문을 읽을 수 없습니다");
   }
 
   try {
-    // If Content-Length is known, pre-allocate for memory efficiency
+    // Content-Length를 알 수 있는 경우, 메모리 효율을 위해 사전 할당
     if (contentLength > 0) {
       const result = new Uint8Array(contentLength);
       let receivedLength = 0;
@@ -33,15 +33,27 @@ export async function fetchUrlBytes(
         const { done, value } = await reader.read();
         if (done) break;
 
+        if (receivedLength + value.length > contentLength) {
+          throw new Error(
+            `수신 데이터가 Content-Length를 초과했습니다 (Content-Length: ${contentLength}, 수신: ${receivedLength + value.length}+)`,
+          );
+        }
+
         result.set(value, receivedLength);
         receivedLength += value.length;
         options?.onProgress?.({ receivedLength, contentLength });
       }
 
+      if (receivedLength < contentLength) {
+        throw new Error(
+          `수신 데이터가 Content-Length보다 부족합니다 (Content-Length: ${contentLength}, 수신: ${receivedLength})`,
+        );
+      }
+
       return result;
     }
 
-    // If Content-Length is unknown, collect chunks then merge (chunked encoding)
+    // Content-Length를 알 수 없는 경우, 청크를 수집 후 병합 (chunked encoding)
     const chunks: Uint8Array[] = [];
 
     while (true) {

package/src/utils/file-dialog.ts

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

package/README.md

@@ -1,106 +0,0 @@
-# @simplysm/core-browser
-
-Simplysm package - Core module (browser). Browser-only utilities including DOM extensions, file downloads, IndexedDB storage, and virtual file system.
-
-## Installation
-
-```bash
-npm install @simplysm/core-browser
-```
-
-## Side-Effect Imports
-
-This package includes side-effect imports that augment global prototypes when the module is loaded:
-
-- `Element.prototype` -- Adds `findAll`, `findFirst`, `prependChild`, `getParents`, `findFocusableParent`, `findFirstFocusableChild`, `isOffsetElement`, `isVisible`.
-- `HTMLElement.prototype` -- Adds `repaint`, `getRelativeOffset`, `scrollIntoViewIfNeeded`.
-
-These side effects run automatically when you import from `@simplysm/core-browser`.
-
-## API Overview
-
-### Element Extensions
-
-| API | Type | Description |
-|-----|------|-------------|
-| `ElementBounds` | interface | Element bounds info (`target`, `top`, `left`, `width`, `height`) |
-| `Element.findAll` | prototype method | Find all child elements matching a CSS selector |
-| `Element.findFirst` | prototype method | Find first element matching a CSS selector |
-| `Element.prependChild` | prototype method | Insert element as first child |
-| `Element.getParents` | prototype method | Get all parent elements (closest to farthest) |
-| `Element.findFocusableParent` | prototype method | Find first focusable parent element |
-| `Element.findFirstFocusableChild` | prototype method | Find first focusable child element |
-| `Element.isOffsetElement` | prototype method | Check if element has offset positioning |
-| `Element.isVisible` | prototype method | Check if element is visible on screen |
-| `copyElement` | function | Copy element content to clipboard via ClipboardEvent |
-| `pasteToElement` | function | Paste clipboard content to element via ClipboardEvent |
-| `getBounds` | function | Get bounds for multiple elements using IntersectionObserver |
-
--> See [docs/element-extensions.md](./docs/element-extensions.md) for details.
-
-### HTMLElement Extensions
-
-| API | Type | Description |
-|-----|------|-------------|
-| `HTMLElement.repaint` | prototype method | Force repaint (triggers reflow) |
-| `HTMLElement.getRelativeOffset` | prototype method | Calculate position relative to a parent element |
-| `HTMLElement.scrollIntoViewIfNeeded` | prototype method | Scroll to make target visible if obscured |
-
--> See [docs/html-element-extensions.md](./docs/html-element-extensions.md) for details.
-
-### Utilities
-
-| API | Type | Description |
-|-----|------|-------------|
-| `downloadBlob` | function | Download a Blob as a file |
-| `DownloadProgress` | interface | Download progress info (`receivedLength`, `contentLength`) |
-| `fetchUrlBytes` | function | Download binary data from URL with progress callback |
-| `openFileDialog` | function | Programmatically open file selection dialog |
-
--> See [docs/utilities.md](./docs/utilities.md) for details.
-
-### Classes
-
-| API | Type | Description |
-|-----|------|-------------|
-| `StoreConfig` | interface | IndexedDB store configuration (`name`, `keyPath`) |
-| `IndexedDbStore` | class | IndexedDB wrapper for key-value storage |
-| `VirtualFsEntry` | interface | Virtual file system entry (`kind`, `dataBase64`) |
-| `IndexedDbVirtualFs` | class | IndexedDB-backed virtual file system |
-
--> See [docs/classes.md](./docs/classes.md) for details.
-
-## Usage Examples
-
-### Download a file
-
-```typescript
-import { downloadBlob } from "@simplysm/core-browser";
-
-const blob = new Blob(["Hello"], { type: "text/plain" });
-downloadBlob(blob, "hello.txt");
-```
-
-### Open file dialog and read files
-
-```typescript
-import { openFileDialog } from "@simplysm/core-browser";
-
-const files = await openFileDialog({ accept: ".csv", multiple: true });
-if (files) {
-  for (const file of files) {
-    const text = await file.text();
-  }
-}
-```
-
-### Use IndexedDB store
-
-```typescript
-import { IndexedDbStore } from "@simplysm/core-browser";
-
-const store = new IndexedDbStore("myApp", 1, [{ name: "settings", keyPath: "key" }]);
-await store.put("settings", { key: "theme", value: "dark" });
-const item = await store.get<{ key: string; value: string }>("settings", "theme");
-store.close();
-```