@simplysm/core-browser 13.0.100 → 14.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/core-browser
 
-Simplysm package - Core module (browser). Browser-only utilities including DOM extensions, file downloads, IndexedDB storage, and virtual file system.
+Core browser utilities -- DOM extensions, file operations, IndexedDB wrappers.
 
 ## Installation
 
@@ -8,99 +8,217 @@ Simplysm package - Core module (browser). Browser-only utilities including DOM e
 npm install @simplysm/core-browser
 ```
 
-## Side-Effect Imports
+## API
 
-This package includes side-effect imports that augment global prototypes when the module is loaded:
+### Extensions
 
-- `Element.prototype` -- Adds `findAll`, `findFirst`, `prependChild`, `getParents`, `findFocusableParent`, `findFirstFocusableChild`, `isOffsetElement`, `isVisible`.
-- `HTMLElement.prototype` -- Adds `repaint`, `getRelativeOffset`, `scrollIntoViewIfNeeded`.
+| Export | Kind | Description |
+|--------|------|-------------|
+| `ElementBounds` | interface | Element bounding rectangle data |
+| Element prototype extensions | side-effect import | DOM query/traversal helpers added to `Element.prototype` |
+| HTMLElement prototype extensions | side-effect import | Repaint, relative offset, scroll helpers added to `HTMLElement.prototype` |
+| `copyElement` | function | Copy element content to clipboard |
+| `pasteToElement` | function | Paste clipboard content to element |
+| `getBounds` | async function | Get element bounds via IntersectionObserver |
 
-These side effects run automatically when you import from `@simplysm/core-browser`.
+### Utils
 
-## API Overview
+| Export | Kind | Description |
+|--------|------|-------------|
+| `downloadBlob` | function | Download a Blob as a file |
+| `DownloadProgress` | interface | Progress info for byte fetching |
+| `fetchUrlBytes` | async function | Fetch URL content as `Uint8Array` with progress |
+| `openFileDialog` | function | Open a native file picker dialog |
+| `StoreConfig` | interface | IndexedDB store configuration |
+| `IndexedDbStore` | class | IndexedDB key-value store wrapper |
+| `VirtualFsEntry` | interface | Virtual filesystem entry descriptor |
+| `IndexedDbVirtualFs` | class | Virtual filesystem backed by IndexedDB |
+
+## Extensions
+
+### ElementBounds (interface)
+
+```ts
+interface ElementBounds {
+  target: Element;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+```
 
-### Element Extensions
+### Element prototype extensions (side-effect import)
 
-| 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 |
+Import `@simplysm/core-browser` to activate these extensions on `Element.prototype`.
 
--> See [docs/element-extensions.md](./docs/element-extensions.md) for details.
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `findAll` | `findAll<TEl>(selector: string): TEl[]` | Find all matching descendants |
+| `findFirst` | `findFirst<TEl>(selector: string): TEl \| undefined` | Find first matching descendant |
+| `prependChild` | `prependChild<TEl>(child: TEl): TEl` | Prepend a child element |
+| `getParents` | `getParents(): Element[]` | Get all ancestor elements |
+| `findFocusableParent` | `findFocusableParent(): HTMLElement \| undefined` | Find nearest focusable ancestor |
+| `findFirstFocusableChild` | `findFirstFocusableChild(): HTMLElement \| undefined` | Find first focusable descendant |
+| `isOffsetElement` | `isOffsetElement(): boolean` | Check if element is an offset parent |
+| `isVisible` | `isVisible(): boolean` | Check if element is visible |
 
-### HTMLElement Extensions
+### HTMLElement prototype extensions (side-effect import)
 
-| 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 |
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `repaint` | `repaint(): void` | Force a repaint of the element |
+| `getRelativeOffset` | `getRelativeOffset(parent: HTMLElement \| string): { top: number; left: number }` | Get position relative to a parent |
+| `scrollIntoViewIfNeeded` | `scrollIntoViewIfNeeded(target: { top: number; left: number }, offset?: { top: number; left: number }): void` | Scroll to make target position visible |
 
--> See [docs/html-element-extensions.md](./docs/html-element-extensions.md) for details.
+### copyElement
 
-### Utilities
+```ts
+function copyElement(event: ClipboardEvent): void
+```
 
-| 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 |
+Copy the content of the focused element to the clipboard via a `ClipboardEvent`.
+
+### pasteToElement
+
+```ts
+function pasteToElement(event: ClipboardEvent): void
+```
+
+Paste clipboard content into the focused element via a `ClipboardEvent`.
+
+### getBounds
+
+```ts
+async function getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>
+```
+
+Get bounding rectangles for multiple elements using `IntersectionObserver`. An optional `timeout` (ms) limits the observation duration.
+
+## Utils
+
+### downloadBlob
+
+```ts
+function downloadBlob(blob: Blob, fileName: string): void
+```
+
+Trigger a browser download for the given `Blob` with the specified file name.
+
+### DownloadProgress (interface)
+
+```ts
+interface DownloadProgress {
+  receivedLength: number;
+  contentLength: number;
+}
+```
 
--> See [docs/utilities.md](./docs/utilities.md) for details.
+### fetchUrlBytes
 
-### Classes
+```ts
+async function fetchUrlBytes(
+  url: string,
+  options?: { onProgress?: (progress: DownloadProgress) => void },
+): Promise<Uint8Array>
+```
 
-| 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 |
+Fetch URL content as a `Uint8Array`. Optionally reports download progress via `onProgress`.
 
--> See [docs/classes.md](./docs/classes.md) for details.
+### openFileDialog
 
-## Usage Examples
+```ts
+function openFileDialog(options?: {
+  accept?: string;
+  multiple?: boolean;
+}): Promise<File[] | undefined>
+```
 
-### Download a file
+Open a native file picker dialog. Returns selected files, or `undefined` if cancelled.
 
-```typescript
-import { downloadBlob } from "@simplysm/core-browser";
+### StoreConfig (interface)
 
-const blob = new Blob(["Hello"], { type: "text/plain" });
-downloadBlob(blob, "hello.txt");
+```ts
+interface StoreConfig {
+  name: string;
+  keyPath: string;
+}
 ```
 
-### Open file dialog and read files
+### IndexedDbStore (class)
+
+IndexedDB wrapper providing simple key-value operations.
 
-```typescript
-import { openFileDialog } from "@simplysm/core-browser";
+**Constructor:**
 
-const files = await openFileDialog({ accept: ".csv", multiple: true });
-if (files) {
-  for (const file of files) {
-    const text = await file.text();
-  }
+```ts
+constructor(dbName: string, dbVersion: number, storeConfigs: StoreConfig[])
+```
+
+**Methods:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `open` | `open(): Promise<IDBDatabase>` | Open the database connection |
+| `withStore` | `withStore<T>(storeName: string, mode: IDBTransactionMode, fn: (store: IDBObjectStore) => IDBRequest<T>): Promise<T>` | Execute a single-store transaction |
+| `get` | `get<T>(storeName: string, key: IDBValidKey): Promise<T \| undefined>` | Get a value by key |
+| `put` | `put(storeName: string, value: unknown): Promise<void>` | Insert or update a value |
+| `delete` | `delete(storeName: string, key: IDBValidKey): Promise<void>` | Delete a value by key |
+| `getAll` | `getAll<T>(storeName: string): Promise<T[]>` | Get all values in a store |
+| `close` | `close(): void` | Close the database connection |
+
+### VirtualFsEntry (interface)
+
+```ts
+interface VirtualFsEntry {
+  kind: "file" | "dir";
+  dataBase64?: string;
 }
 ```
 
-### Use IndexedDB store
+### IndexedDbVirtualFs (class)
+
+Virtual filesystem backed by an `IndexedDbStore`. Stores files and directories as entries in IndexedDB.
+
+**Constructor:**
+
+```ts
+constructor(db: IndexedDbStore, storeName: string, keyField: string)
+```
+
+**Methods:**
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `getEntry` | `getEntry(fullKey: string): Promise<VirtualFsEntry \| undefined>` | Get a filesystem entry by key |
+| `putEntry` | `putEntry(fullKey: string, kind: "file" \| "dir", dataBase64?: string): Promise<void>` | Create or update a filesystem entry |
+| `deleteByPrefix` | `deleteByPrefix(keyPrefix: string): Promise<boolean>` | Delete all entries matching a key prefix |
+| `listChildren` | `listChildren(prefix: string): Promise<{ name: string; isDirectory: boolean }[]>` | List immediate children of a directory |
+| `ensureDir` | `ensureDir(fullKeyBuilder: (dir: string) => string, dirPath: string): Promise<void>` | Recursively ensure a directory path exists |
+
+## Usage
+
+```ts
+import "@simplysm/core-browser"; // activate prototype extensions
+
+// DOM extensions
+const el = document.querySelector(".my-element")!;
+const parents = el.getParents();
+const child = el.findFirst<HTMLDivElement>(".child");
+
+// File download
+import { downloadBlob, fetchUrlBytes } from "@simplysm/core-browser";
+
+const bytes = await fetchUrlBytes("/api/data.bin", {
+  onProgress: (p) => console.log(`${p.receivedLength}/${p.contentLength}`),
+});
+downloadBlob(new Blob([bytes]), "data.bin");
 
-```typescript
+// IndexedDB store
 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");
+const store = new IndexedDbStore("myDb", 1, [{ name: "items", keyPath: "id" }]);
+await store.put("items", { id: "1", value: "hello" });
+const item = await store.get("items", "1");
 store.close();
 ```

package/dist/extensions/element-ext.d.ts

@@ -1,98 +1,98 @@
 /**
- * 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;
     }
 }
 /**
- * Copy element content to clipboard (use with copy event handler)
+ * 요소 내용을 클립보드에 복사 (copy 이벤트 핸들러와 함께 사용)
  *
- * @param event - copy event object
+ * @param event - copy 이벤트 객체
  */
 export declare 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 declare 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 declare function getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>;
 //# sourceMappingURL=element-ext.d.ts.map

package/dist/extensions/element-ext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"element-ext.d.ts","sourceRoot":"","sources":["..\\..\\src\\extensions\\element-ext.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,6BAA6B;IAC7B,MAAM,EAAE,OAAO,CAAC;IAChB,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO;QACf;;;;;WAKG;QACH,OAAO,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,EAAE,CAAC;QAEhE;;;;;WAKG;QACH,SAAS,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;QAE5E;;;;;WAKG;QACH,YAAY,CAAC,GAAG,SAAS,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,GAAG,CAAC;QAEnD;;;;WAIG;QACH,UAAU,IAAI,OAAO,EAAE,CAAC;QAExB;;;;WAIG;QACH,mBAAmB,IAAI,WAAW,GAAG,SAAS,CAAC;QAE/C;;;;WAIG;QACH,uBAAuB,IAAI,WAAW,GAAG,SAAS,CAAC;QAEnD;;;;WAIG;QACH,eAAe,IAAI,OAAO,CAAC;QAE3B;;;;;;;WAOG;QACH,SAAS,IAAI,OAAO,CAAC;KACtB;CACF;AAkED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAYvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAa1D;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAoDhG"}
+{"version":3,"file":"element-ext.d.ts","sourceRoot":"","sources":["..\\..\\src\\extensions\\element-ext.ts"],"names":[],"mappings":"AAGA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,eAAe;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,mBAAmB;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,YAAY;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,OAAO;QACf;;;;;WAKG;QACH,OAAO,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,EAAE,CAAC;QAEhE;;;;;WAKG;QACH,SAAS,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAAC;QAE5E;;;;;WAKG;QACH,YAAY,CAAC,GAAG,SAAS,OAAO,EAAE,KAAK,EAAE,GAAG,GAAG,GAAG,CAAC;QAEnD;;;;WAIG;QACH,UAAU,IAAI,OAAO,EAAE,CAAC;QAExB;;;;WAIG;QACH,mBAAmB,IAAI,WAAW,GAAG,SAAS,CAAC;QAE/C;;;;WAIG;QACH,uBAAuB,IAAI,WAAW,GAAG,SAAS,CAAC;QAEnD;;;;WAIG;QACH,eAAe,IAAI,OAAO,CAAC;QAE3B;;;;;;;WAOG;QACH,SAAS,IAAI,OAAO,CAAC;KACtB;CACF;AAkED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAYvD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAa1D;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,OAAO,GAAE,MAAa,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAoDhG"}