@simplysm/core-browser 14.0.1 → 14.0.4

package/README.md

@@ -0,0 +1,224 @@
+# @simplysm/core-browser
+
+Core browser utilities -- DOM extensions, file operations, IndexedDB wrappers.
+
+## Installation
+
+```bash
+npm install @simplysm/core-browser
+```
+
+## API
+
+### Extensions
+
+| 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 |
+
+### Utils
+
+| 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 prototype extensions (side-effect import)
+
+Import `@simplysm/core-browser` to activate these extensions on `Element.prototype`.
+
+| 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 prototype extensions (side-effect import)
+
+| 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 |
+
+### copyElement
+
+```ts
+function copyElement(event: ClipboardEvent): void
+```
+
+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;
+}
+```
+
+### fetchUrlBytes
+
+```ts
+async function fetchUrlBytes(
+  url: string,
+  options?: { onProgress?: (progress: DownloadProgress) => void },
+): Promise<Uint8Array>
+```
+
+Fetch URL content as a `Uint8Array`. Optionally reports download progress via `onProgress`.
+
+### openFileDialog
+
+```ts
+function openFileDialog(options?: {
+  accept?: string;
+  multiple?: boolean;
+}): Promise<File[] | undefined>
+```
+
+Open a native file picker dialog. Returns selected files, or `undefined` if cancelled.
+
+### StoreConfig (interface)
+
+```ts
+interface StoreConfig {
+  name: string;
+  keyPath: string;
+}
+```
+
+### IndexedDbStore (class)
+
+IndexedDB wrapper providing simple key-value operations.
+
+**Constructor:**
+
+```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;
+}
+```
+
+### 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");
+
+// IndexedDB store
+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("items", "1");
+store.close();
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-browser",
-  "version": "14.0.1",
+  "version": "14.0.4",
   "description": "심플리즘 패키지 - 코어 (browser)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -24,6 +24,6 @@
   ],
   "dependencies": {
     "tabbable": "^6.4.0",
-    "@simplysm/core-common": "14.0.1"
+    "@simplysm/core-common": "14.0.4"
   }
 }