@simplysm/core-browser 13.0.42 → 13.0.43

package/README.md

@@ -20,14 +20,14 @@ Instance methods automatically added to `Element.prototype` when importing `"@si
 
 | Method | Return Type | Description |
 |--------|-----------|------|
-| `findAll<T>(selector)` | `T[]` | Search all descendant elements by selector |
-| `findFirst<T>(selector)` | `T \| undefined` | Search first matching element by selector |
-| `prependChild<T>(child)` | `T` | Insert element as first child |
+| `findAll<T>(selector: string)` | `T[]` | Search all descendant elements by selector. Returns empty array for empty selector. |
+| `findFirst<T>(selector: string)` | `T \| undefined` | Search first matching element by selector. Returns `undefined` for empty selector. |
+| `prependChild<T>(child: T)` | `T` | Insert element as first child |
 | `getParents()` | `Element[]` | Return list of all parent elements (closest first) |
-| `findFocusableParent()` | `HTMLElement \| undefined` | Search for first focusable element among parents |
-| `findFirstFocusableChild()` | `HTMLElement \| undefined` | Search for first focusable element among children |
-| `isOffsetElement()` | `boolean` | Check if element is an offset reference element |
-| `isVisible()` | `boolean` | Check element visibility |
+| `findFocusableParent()` | `HTMLElement \| undefined` | Search for first focusable element among parents (uses tabbable) |
+| `findFirstFocusableChild()` | `HTMLElement \| undefined` | Search for first focusable element among children (uses tabbable) |
+| `isOffsetElement()` | `boolean` | Check if element has `position: relative`, `absolute`, `fixed`, or `sticky` |
+| `isVisible()` | `boolean` | Check element visibility (clientRects exist, not `visibility: hidden`, not `opacity: 0`) |
 
 ### HTMLElement Extension Methods
 
@@ -35,37 +35,37 @@ Instance methods automatically added to `HTMLElement.prototype`.
 
 | Method | Return Type | Description |
 |--------|-----------|------|
-| `repaint()` | `void` | Trigger forced repaint (triggers forced synchronous layout) |
-| `getRelativeOffset(parent: HTMLElement \| string)` | `{ top: number; left: number }` | Calculate relative position based on parent element or CSS selector |
-| `scrollIntoViewIfNeeded(target, offset?)` | `void` | Adjust scroll if target is obscured by fixed regions (top/left only) |
+| `repaint()` | `void` | Trigger forced repaint by causing forced synchronous layout |
+| `getRelativeOffset(parent: HTMLElement \| string)` | `{ top: number; left: number }` | Calculate document-based position relative to a parent element or CSS selector, suitable for CSS `top`/`left` (includes `window.scrollX/Y`, parent scroll, border widths, and CSS transforms) |
+| `scrollIntoViewIfNeeded(target: { top: number; left: number }, offset?: { top: number; left: number })` | `void` | Adjust scroll so that target position is visible past any fixed offset regions (top/left only) |
 
 ### Static Functions
 
 | Function | Return Type | Description |
 |------|-----------|------|
-| `copyElement(event)` | `void` | Copy element content to clipboard |
-| `pasteToElement(event)` | `void` | Paste clipboard content into element |
-| `getBounds(els, timeout?)` | `Promise<ElementBounds[]>` | Query element bounds using IntersectionObserver |
+| `copyElement(event: ClipboardEvent)` | `void` | Copy value of first `input`/`textarea` within the event target element to clipboard |
+| `pasteToElement(event: ClipboardEvent)` | `void` | Paste clipboard text into the first `input`/`textarea` within the event target element |
+| `getBounds(els: Element[], timeout?: number)` | `Promise<ElementBounds[]>` | Query element bounds using `IntersectionObserver`. Results are returned in input order. Default timeout: 5000ms. |
 
 ### Download Utilities
 
 | Function | Return Type | Description |
 |------|-----------|------|
-| `downloadBlob(blob, fileName)` | `void` | Download Blob as file |
-| `fetchUrlBytes(url, options?)` | `Promise<Uint8Array>` | Download binary data from URL (with progress callback support) |
+| `downloadBlob(blob: Blob, fileName: string)` | `void` | Download a Blob as a file |
+| `fetchUrlBytes(url: string, options?: { onProgress?: (progress: DownloadProgress) => void })` | `Promise<Uint8Array>` | Download binary data from a URL with optional progress callback |
 
 ### File Dialog
 
 | Function | Return Type | Description |
 |------|-----------|------|
-| `openFileDialog(options?)` | `Promise<File[] \| undefined>` | Open file selection dialog (supports single/multiple file selection) |
+| `openFileDialog(options?: { accept?: string; multiple?: boolean })` | `Promise<File[] \| undefined>` | Open a file selection dialog. Returns `undefined` if the user cancels without selecting. |
 
 ### Types
 
 | Type | Description |
 |------|------|
-| `ElementBounds` | Element bounds information (`target`, `top`, `left`, `width`, `height`) |
-| `DownloadProgress` | Download progress information (`receivedLength`, `contentLength`) |
+| `ElementBounds` | Element bounds information: `target: Element`, `top: number`, `left: number`, `width: number`, `height: number` |
+| `DownloadProgress` | Download progress: `receivedLength: number`, `contentLength: number` |
 
 ## Usage Examples
 
@@ -107,12 +107,12 @@ import "@simplysm/core-browser";
 // Forced repaint (useful for restarting CSS animations)
 element.repaint();
 
-// Calculate relative position based on parent element (can be used directly for CSS top/left)
+// Calculate document-based position relative to a parent element (can be used directly for CSS top/left)
 const offset = element.getRelativeOffset(document.body);
 popup.style.top = `${offset.top}px`;
 popup.style.left = `${offset.left}px`;
 
-// Parent can also be specified by selector
+// Parent can also be specified by CSS selector (uses closest())
 const offset2 = element.getRelativeOffset(".scroll-container");
 
 // Adjust scroll position in table with fixed header/columns
@@ -131,11 +131,11 @@ scrollContainer.scrollIntoViewIfNeeded(
 import { copyElement, pasteToElement } from "@simplysm/core-browser";
 
 // Use in copy event handler
-// Copy value of first input/textarea within target element to clipboard
+// Copies value of the first input/textarea within the target element to clipboard
 element.addEventListener("copy", (e) => copyElement(e));
 
 // Use in paste event handler
-// Paste clipboard content into first input/textarea within target element
+// Pastes clipboard content into the first input/textarea within the target element
 element.addEventListener("paste", (e) => pasteToElement(e));
 ```
 
@@ -229,11 +229,11 @@ if (selectedFiles) {
 
 - This package is **browser-only**. It cannot be used in Node.js environments.
 - `Element` and `HTMLElement` prototype extensions work as **side-effect imports**. Extensions are automatically applied when importing `"@simplysm/core-browser"` or any item from the package.
-- The `getBounds()` function uses `IntersectionObserver` and works asynchronously. If all elements are not observed within the specified timeout (default 5000ms), a `TimeoutError` is thrown.
-- The `getRelativeOffset()` method accepts either an `HTMLElement` or a CSS selector string as the `parent` parameter. It throws `ArgumentError` if the parent element cannot be found. Border thickness and scroll position of intermediate elements are included in the calculation, and CSS `transform` is correctly handled.
+- The `getBounds()` function uses `IntersectionObserver` and works asynchronously. If all elements are not observed within the specified timeout (default 5000ms), a `TimeoutError` is thrown. Duplicate elements in the input array are deduplicated; results are returned in input order.
+- The `getRelativeOffset()` method accepts either an `HTMLElement` or a CSS selector string as the `parent` parameter. When a string is given, it uses `closest()` to find the nearest matching ancestor. It throws `ArgumentError` if the parent element cannot be found. The returned coordinates are document-based (include `window.scrollX/Y`) and are suitable for use as CSS `top`/`left` values. Intermediate element border widths, parent scroll position, and CSS `transform` are all included in the calculation.
 - The `scrollIntoViewIfNeeded()` method only handles cases where the target is beyond the top/left boundaries. The bottom/right directions rely on the browser's default focus scrolling.
-- The `fetchUrlBytes()` function improves memory efficiency by pre-allocating when the `Content-Length` header is available, and collects and merges chunks for chunked encoding.
-- The `pasteToElement()` function replaces the entire value of the target input/textarea. It does not consider cursor position or selection range.
+- The `fetchUrlBytes()` function improves memory efficiency by pre-allocating a buffer when the `Content-Length` header is available, and collects and merges chunks for chunked encoding. Throws an `Error` if the response status is not ok or if the response body is not readable.
+- The `pasteToElement()` function replaces the entire value of the target input/textarea. It does not consider cursor position or selection range. It dispatches an `input` event after the value is set.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-browser",
-  "version": "13.0.42",
+  "version": "13.0.43",
   "description": "심플리즘 패키지 - 코어 모듈 (browser)",
   "author": "김석래",
   "license": "Apache-2.0",
@@ -22,7 +22,7 @@
   ],
   "dependencies": {
     "tabbable": "^6.4.0",
-    "@simplysm/core-common": "13.0.42"
+    "@simplysm/core-common": "13.0.43"
   },
   "devDependencies": {
     "happy-dom": "^20.6.3"