@simplysm/core-browser 14.0.1 → 14.0.5

package/README.md

@@ -0,0 +1,151 @@
+# @simplysm/core-browser
+
+Browser-specific core utilities for the Simplysm framework. Provides DOM element extensions, download/fetch helpers, file dialog, and IndexedDB abstractions.
+
+## Installation
+
+```bash
+npm install @simplysm/core-browser
+```
+
+## API Overview
+
+### Element Extensions
+
+| API | Type | Description |
+|-----|------|-------------|
+| `ElementBounds` | interface | Bounding rect info for an element |
+| `Element.prototype.findAll` | method | Find all descendant elements matching a CSS selector |
+| `Element.prototype.findFirst` | method | Find the first descendant element matching a CSS selector |
+| `Element.prototype.prependChild` | method | Insert a child as the first element child |
+| `Element.prototype.getParents` | method | Get all ancestor elements (nearest first) |
+| `Element.prototype.findFocusableParent` | method | Find the nearest focusable ancestor |
+| `Element.prototype.findFirstFocusableChild` | method | Find the first focusable descendant |
+| `Element.prototype.isOffsetElement` | method | Check if element is an offset parent |
+| `Element.prototype.isVisible` | method | Check if element is visible on screen |
+| `copyElement` | function | Copy element content to clipboard via ClipboardEvent |
+| `pasteToElement` | function | Paste clipboard content into element via ClipboardEvent |
+| `getBounds` | function | Get bounding info for multiple elements using IntersectionObserver |
+
+> See [docs/element-extensions.md](./docs/element-extensions.md) for details.
+
+### HTML Element Extensions
+
+| API | Type | Description |
+|-----|------|-------------|
+| `HTMLElement.prototype.repaint` | method | Force a synchronous repaint |
+| `HTMLElement.prototype.getRelativeOffset` | method | Calculate position relative to a parent element |
+| `HTMLElement.prototype.scrollIntoViewIfNeeded` | method | Scroll container so target is not hidden by offset areas |
+
+> See [docs/html-element-extensions.md](./docs/html-element-extensions.md) for details.
+
+### Download
+
+| API | Type | Description |
+|-----|------|-------------|
+| `downloadBlob` | function | Download a Blob as a file |
+
+> See [docs/download.md](./docs/download.md) for details.
+
+### Fetch
+
+| API | Type | Description |
+|-----|------|-------------|
+| `DownloadProgress` | interface | Progress info for fetch downloads |
+| `fetchUrlBytes` | function | Download binary data from a URL with progress callback |
+
+> See [docs/fetch.md](./docs/fetch.md) for details.
+
+### File Dialog
+
+| API | Type | Description |
+|-----|------|-------------|
+| `openFileDialog` | function | Programmatically open a file picker dialog |
+
+> See [docs/file-dialog.md](./docs/file-dialog.md) for details.
+
+### IndexedDB Store
+
+| API | Type | Description |
+|-----|------|-------------|
+| `StoreConfig` | interface | Configuration for an IndexedDB object store |
+| `IndexedDbStore` | class | Generic IndexedDB wrapper with CRUD operations |
+
+> See [docs/indexed-db-store.md](./docs/indexed-db-store.md) for details.
+
+### IndexedDB Virtual FS
+
+| API | Type | Description |
+|-----|------|-------------|
+| `VirtualFsEntry` | interface | Entry representing a file or directory in the virtual FS |
+| `IndexedDbVirtualFs` | class | Virtual file system backed by IndexedDB |
+
+> See [docs/indexed-db-virtual-fs.md](./docs/indexed-db-virtual-fs.md) for details.
+
+## Usage Examples
+
+### Copy/Paste with ClipboardEvent
+
+```typescript
+import { copyElement, pasteToElement } from "@simplysm/core-browser";
+
+document.addEventListener("copy", (event) => copyElement(event));
+document.addEventListener("paste", (event) => pasteToElement(event));
+```
+
+### Download a Blob
+
+```typescript
+import { downloadBlob } from "@simplysm/core-browser";
+
+const blob = new Blob(["hello"], { type: "text/plain" });
+downloadBlob(blob, "hello.txt");
+```
+
+### Fetch binary data with progress
+
+```typescript
+import { fetchUrlBytes } from "@simplysm/core-browser";
+
+const data = await fetchUrlBytes("/api/file.bin", {
+  onProgress: ({ receivedLength, contentLength }) => {
+    console.log(`${receivedLength} / ${contentLength}`);
+  },
+});
+```
+
+### Open a file dialog
+
+```typescript
+import { openFileDialog } from "@simplysm/core-browser";
+
+const files = await openFileDialog({ accept: ".csv", multiple: true });
+if (files) {
+  for (const file of files) {
+    console.log(file.name);
+  }
+}
+```
+
+### IndexedDB Store
+
+```typescript
+import { IndexedDbStore } from "@simplysm/core-browser";
+
+const store = new IndexedDbStore("myDb", 1, [{ name: "items", keyPath: "id" }]);
+await store.put("items", { id: "1", value: "hello" });
+const item = await store.get<{ id: string; value: string }>("items", "1");
+store.close();
+```
+
+### Get element bounds
+
+```typescript
+import { getBounds } from "@simplysm/core-browser";
+
+const elements = document.querySelectorAll(".card");
+const bounds = await getBounds([...elements]);
+for (const b of bounds) {
+  console.log(`${b.target.tagName}: ${b.top}, ${b.left}, ${b.width}x${b.height}`);
+}
+```

package/docs/download.md

@@ -0,0 +1,16 @@
+# Download
+
+Utility for triggering file downloads in the browser.
+
+## `downloadBlob`
+
+Download a `Blob` as a file by creating a temporary object URL and clicking a hidden anchor element. The object URL is revoked after 1 second.
+
+```typescript
+function downloadBlob(blob: Blob, fileName: string): void
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `blob` | `Blob` | The Blob to download |
+| `fileName` | `string` | File name for the download |

package/docs/element-extensions.md

@@ -0,0 +1,158 @@
+# Element Extensions
+
+Side-effect import that extends the global `Element` prototype with DOM utility methods, plus standalone clipboard and bounds functions.
+
+## `ElementBounds`
+
+Bounding rectangle information for an element, returned by `getBounds`.
+
+```typescript
+interface ElementBounds {
+  target: Element;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `Element` | The measured element |
+| `top` | `number` | Top position relative to viewport |
+| `left` | `number` | Left position relative to viewport |
+| `width` | `number` | Element width |
+| `height` | `number` | Element height |
+
+## `Element.prototype.findAll`
+
+Find all descendant elements matching a CSS selector.
+
+```typescript
+findAll<TEl extends Element = Element>(selector: string): TEl[]
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `selector` | `string` | CSS selector. Returns empty array if empty string. |
+
+**Returns:** `TEl[]` -- Array of matching elements.
+
+## `Element.prototype.findFirst`
+
+Find the first descendant element matching a CSS selector.
+
+```typescript
+findFirst<TEl extends Element = Element>(selector: string): TEl | undefined
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `selector` | `string` | CSS selector. Returns `undefined` if empty string. |
+
+**Returns:** `TEl | undefined` -- First matching element or `undefined`.
+
+## `Element.prototype.prependChild`
+
+Insert a child element as the first child.
+
+```typescript
+prependChild<TEl extends Element>(child: TEl): TEl
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `child` | `TEl` | Element to insert |
+
+**Returns:** `TEl` -- The inserted child element.
+
+## `Element.prototype.getParents`
+
+Get all ancestor elements, ordered from nearest to farthest.
+
+```typescript
+getParents(): Element[]
+```
+
+**Returns:** `Element[]` -- Array of parent elements (nearest first).
+
+## `Element.prototype.findFocusableParent`
+
+Find the nearest focusable ancestor element (uses `tabbable` library).
+
+```typescript
+findFocusableParent(): HTMLElement | undefined
+```
+
+**Returns:** `HTMLElement | undefined` -- First focusable parent or `undefined`.
+
+## `Element.prototype.findFirstFocusableChild`
+
+Find the first focusable descendant element (uses `tabbable` library).
+
+```typescript
+findFirstFocusableChild(): HTMLElement | undefined
+```
+
+**Returns:** `HTMLElement | undefined` -- First focusable child or `undefined`.
+
+## `Element.prototype.isOffsetElement`
+
+Check whether the element is an offset parent (`position: relative | absolute | fixed | sticky`).
+
+```typescript
+isOffsetElement(): boolean
+```
+
+**Returns:** `boolean` -- `true` if element has a positioning CSS property.
+
+## `Element.prototype.isVisible`
+
+Check whether the element is visible on screen. Checks `getClientRects()`, `visibility`, and `opacity`.
+
+```typescript
+isVisible(): boolean
+```
+
+**Returns:** `boolean` -- `true` if the element is visible.
+
+## `copyElement`
+
+Copy element content to the clipboard. Intended for use as a `copy` event handler. Finds the first `input` or `textarea` within the event target and copies its value.
+
+```typescript
+function copyElement(event: ClipboardEvent): void
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `event` | `ClipboardEvent` | The copy event object |
+
+## `pasteToElement`
+
+Paste clipboard content into an element. Intended for use as a `paste` event handler. Finds the first `input` or `textarea` within the event target and replaces its entire value with the clipboard text.
+
+```typescript
+function pasteToElement(event: ClipboardEvent): void
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `event` | `ClipboardEvent` | The paste event object |
+
+## `getBounds`
+
+Get bounding rectangle information for multiple elements using `IntersectionObserver`. Results are returned in the same order as the input array. Duplicate elements are deduplicated.
+
+```typescript
+async function getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `els` | `Element[]` | | Target elements |
+| `timeout` | `number` | `5000` | Timeout in milliseconds |
+
+**Returns:** `Promise<ElementBounds[]>` -- Bounding info sorted by input order.
+
+**Throws:** `TimeoutError` if the observer does not respond within the timeout.

package/docs/fetch.md

@@ -0,0 +1,39 @@
+# Fetch
+
+Utility for downloading binary data from a URL with optional progress tracking.
+
+## `DownloadProgress`
+
+Progress information emitted during a fetch download.
+
+```typescript
+interface DownloadProgress {
+  receivedLength: number;
+  contentLength: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `receivedLength` | `number` | Bytes received so far |
+| `contentLength` | `number` | Total content length from the `Content-Length` header |
+
+## `fetchUrlBytes`
+
+Download binary data from a URL. Supports progress callbacks via `ReadableStream` reader. When the `Content-Length` header is available, the result buffer is pre-allocated for efficiency. When unavailable (chunked encoding), chunks are collected and concatenated.
+
+```typescript
+async function fetchUrlBytes(
+  url: string,
+  options?: { onProgress?: (progress: DownloadProgress) => void },
+): Promise<Uint8Array>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | URL to fetch |
+| `options.onProgress` | `(progress: DownloadProgress) => void` | Optional progress callback |
+
+**Returns:** `Promise<Uint8Array>` -- The downloaded binary data.
+
+**Throws:** `Error` if the response is not OK or the body cannot be read.

package/docs/file-dialog.md

@@ -0,0 +1,21 @@
+# File Dialog
+
+Utility for programmatically opening a native file picker dialog.
+
+## `openFileDialog`
+
+Open a file selection dialog by creating and clicking a hidden `<input type="file">` element. Returns the selected files or `undefined` if the dialog is cancelled.
+
+```typescript
+function openFileDialog(options?: {
+  accept?: string;
+  multiple?: boolean;
+}): Promise<File[] | undefined>
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `options.accept` | `string` | `undefined` | File type filter (e.g., `".csv"`, `"image/*"`) |
+| `options.multiple` | `boolean` | `false` | Allow selecting multiple files |
+
+**Returns:** `Promise<File[] | undefined>` -- Selected files array, or `undefined` if cancelled or no files selected.

package/docs/html-element-extensions.md

@@ -0,0 +1,50 @@
+# HTML Element Extensions
+
+Side-effect import that extends the global `HTMLElement` prototype with layout and scroll utility methods.
+
+## `HTMLElement.prototype.repaint`
+
+Force a synchronous repaint by triggering a reflow (reads `offsetHeight`).
+
+```typescript
+repaint(): void
+```
+
+## `HTMLElement.prototype.getRelativeOffset`
+
+Calculate the element's position relative to a parent element. Returns document-based coordinates (including `window.scrollX/Y`) suitable for CSS `top`/`left` properties.
+
+The calculation accounts for:
+- Viewport position (`getBoundingClientRect`)
+- Document scroll (`window.scrollX/Y`)
+- Parent internal scroll (`parentEl.scrollTop/Left`)
+- Intermediate element border widths
+- CSS `transform`
+
+```typescript
+getRelativeOffset(parent: HTMLElement | string): { top: number; left: number }
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `parent` | `HTMLElement \| string` | Parent element or CSS selector to match via `closest()` |
+
+**Returns:** `{ top: number; left: number }` -- Coordinates usable for CSS `top`/`left`.
+
+**Throws:** `ArgumentError` if the parent element cannot be found.
+
+## `HTMLElement.prototype.scrollIntoViewIfNeeded`
+
+Scroll the container so that the target position is not obscured by fixed offset areas (e.g., sticky headers or fixed columns). Only handles cases where the target is above or to the left of the visible area; downward/rightward scrolling relies on the browser's default focus scroll behavior.
+
+```typescript
+scrollIntoViewIfNeeded(
+  target: { top: number; left: number },
+  offset?: { top: number; left: number },
+): void
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `target` | `{ top: number; left: number }` | | Target position within the container (`offsetTop`, `offsetLeft`) |
+| `offset` | `{ top: number; left: number }` | `{ top: 0, left: 0 }` | Size of the offset area that must not obscure the target (e.g., fixed header height) |

package/docs/indexed-db-store.md

@@ -0,0 +1,103 @@
+# IndexedDB Store
+
+Generic IndexedDB wrapper providing typed CRUD operations and transaction management.
+
+## `StoreConfig`
+
+Configuration for an IndexedDB object store, used when opening the database.
+
+```typescript
+interface StoreConfig {
+  name: string;
+  keyPath: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Object store name |
+| `keyPath` | `string` | Key path for the object store |
+
+## `IndexedDbStore`
+
+A wrapper around the IndexedDB API with automatic database opening, version upgrade handling, and typed CRUD methods.
+
+```typescript
+class IndexedDbStore {
+  constructor(dbName: string, dbVersion: number, storeConfigs: StoreConfig[]);
+}
+```
+
+| Constructor Parameter | Type | Description |
+|----------------------|------|-------------|
+| `dbName` | `string` | Database name |
+| `dbVersion` | `number` | Database version (triggers `onupgradeneeded` when increased) |
+| `storeConfigs` | `StoreConfig[]` | Object store configurations to create on upgrade |
+
+### Methods
+
+#### `open`
+
+Open the database (creates stores on version upgrade). Returns the existing connection if already open. Concurrent calls return the same pending promise.
+
+```typescript
+async open(): Promise<IDBDatabase>
+```
+
+#### `withStore`
+
+Execute a function within a transaction on a specific store. Handles transaction commit/abort automatically.
+
+```typescript
+async withStore<TResult>(
+  storeName: string,
+  mode: IDBTransactionMode,
+  fn: (store: IDBObjectStore) => Promise<TResult>,
+): Promise<TResult>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `storeName` | `string` | Target object store name |
+| `mode` | `IDBTransactionMode` | `"readonly"` or `"readwrite"` |
+| `fn` | `(store: IDBObjectStore) => Promise<TResult>` | Function to execute within the transaction |
+
+#### `get`
+
+Get a single value by key.
+
+```typescript
+async get<TValue>(storeName: string, key: IDBValidKey): Promise<TValue | undefined>
+```
+
+#### `put`
+
+Insert or update a value.
+
+```typescript
+async put(storeName: string, value: unknown): Promise<void>
+```
+
+#### `delete`
+
+Delete a value by key.
+
+```typescript
+async delete(storeName: string, key: IDBValidKey): Promise<void>
+```
+
+#### `getAll`
+
+Get all values from a store.
+
+```typescript
+async getAll<TItem>(storeName: string): Promise<TItem[]>
+```
+
+#### `close`
+
+Close the database connection.
+
+```typescript
+close(): void
+```

package/docs/indexed-db-virtual-fs.md

@@ -0,0 +1,107 @@
+# IndexedDB Virtual FS
+
+A virtual file system abstraction backed by IndexedDB, built on top of `IndexedDbStore`.
+
+## `VirtualFsEntry`
+
+Represents a file or directory entry in the virtual file system.
+
+```typescript
+interface VirtualFsEntry {
+  kind: "file" | "dir";
+  dataBase64?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `kind` | `"file" \| "dir"` | Entry type |
+| `dataBase64` | `string \| undefined` | Base64-encoded file data (only for files) |
+
+## `IndexedDbVirtualFs`
+
+Virtual file system that stores entries in an `IndexedDbStore`. Supports hierarchical path-based operations including directory creation, prefix-based deletion, and child listing.
+
+```typescript
+class IndexedDbVirtualFs {
+  constructor(db: IndexedDbStore, storeName: string, keyField: string);
+}
+```
+
+| Constructor Parameter | Type | Description |
+|----------------------|------|-------------|
+| `db` | `IndexedDbStore` | The IndexedDB store instance |
+| `storeName` | `string` | Object store name to use |
+| `keyField` | `string` | Field name used as the key in the store |
+
+### Methods
+
+#### `getEntry`
+
+Get a virtual FS entry by its full key.
+
+```typescript
+async getEntry(fullKey: string): Promise<VirtualFsEntry | undefined>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fullKey` | `string` | Full key identifying the entry |
+
+#### `putEntry`
+
+Insert or update a virtual FS entry.
+
+```typescript
+async putEntry(fullKey: string, kind: "file" | "dir", dataBase64?: string): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fullKey` | `string` | Full key for the entry |
+| `kind` | `"file" \| "dir"` | Entry type |
+| `dataBase64` | `string` | Optional base64-encoded data (for files) |
+
+#### `deleteByPrefix`
+
+Delete all entries whose key matches the given prefix or starts with `prefix + "/"`.
+
+```typescript
+async deleteByPrefix(keyPrefix: string): Promise<boolean>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `keyPrefix` | `string` | Key prefix to match |
+
+**Returns:** `Promise<boolean>` -- `true` if at least one entry was deleted.
+
+#### `listChildren`
+
+List immediate children under a given prefix. Returns each child's name and whether it is a directory.
+
+```typescript
+async listChildren(prefix: string): Promise<{ name: string; isDirectory: boolean }[]>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `prefix` | `string` | Parent path prefix (e.g., `"/root/dir/"`) |
+
+**Returns:** `Promise<{ name: string; isDirectory: boolean }[]>` -- Array of child entries.
+
+#### `ensureDir`
+
+Ensure all directories along a path exist, creating missing ones.
+
+```typescript
+async ensureDir(
+  fullKeyBuilder: (path: string) => string,
+  dirPath: string,
+): Promise<void>
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fullKeyBuilder` | `(path: string) => string` | Function to build the full key from a path segment |
+| `dirPath` | `string` | Directory path to ensure (e.g., `"/a/b/c"`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-browser",
-  "version": "14.0.1",
+  "version": "14.0.5",
   "description": "심플리즘 패키지 - 코어 (browser)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,7 +14,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": [
     "./src/extensions/element-ext.ts",
@@ -24,6 +25,6 @@
   ],
   "dependencies": {
     "tabbable": "^6.4.0",
-    "@simplysm/core-common": "14.0.1"
+    "@simplysm/core-common": "14.0.5"
   }
 }