@simplysm/core-browser 14.0.4 → 14.0.6

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/core-browser
 
-Core browser utilities -- DOM extensions, file operations, IndexedDB wrappers.
+Browser-specific core utilities for the Simplysm framework. Provides DOM element extensions, download/fetch helpers, file dialog, and IndexedDB abstractions.
 
 ## Installation
 
@@ -8,217 +8,144 @@ Core browser utilities -- DOM extensions, file operations, IndexedDB wrappers.
 npm install @simplysm/core-browser
 ```
 
-## API
+## API Overview
 
-### Extensions
+### Element 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 |
+| 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 |
 
-### Utils
+> See [docs/element-extensions.md](./docs/element-extensions.md) for details.
 
-| 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`.
+### HTML Element Extensions
 
-| 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 |
+| 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 |
 
-### HTMLElement prototype extensions (side-effect import)
+> See [docs/html-element-extensions.md](./docs/html-element-extensions.md) for details.
 
-| 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 |
+### Download
 
-### copyElement
-
-```ts
-function copyElement(event: ClipboardEvent): void
-```
-
-Copy the content of the focused element to the clipboard via a `ClipboardEvent`.
+| API | Type | Description |
+|-----|------|-------------|
+| `downloadBlob` | function | Download a Blob as a file |
 
-### pasteToElement
+> See [docs/download.md](./docs/download.md) for details.
 
-```ts
-function pasteToElement(event: ClipboardEvent): void
-```
+### Fetch
 
-Paste clipboard content into the focused element via a `ClipboardEvent`.
+| API | Type | Description |
+|-----|------|-------------|
+| `DownloadProgress` | interface | Progress info for fetch downloads |
+| `fetchUrlBytes` | function | Download binary data from a URL with progress callback |
 
-### getBounds
+> See [docs/fetch.md](./docs/fetch.md) for details.
 
-```ts
-async function getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>
-```
+### File Dialog
 
-Get bounding rectangles for multiple elements using `IntersectionObserver`. An optional `timeout` (ms) limits the observation duration.
+| API | Type | Description |
+|-----|------|-------------|
+| `openFileDialog` | function | Programmatically open a file picker dialog |
 
-## Utils
+> See [docs/file-dialog.md](./docs/file-dialog.md) for details.
 
-### downloadBlob
+### IndexedDB Store
 
-```ts
-function downloadBlob(blob: Blob, fileName: string): void
-```
+| API | Type | Description |
+|-----|------|-------------|
+| `StoreConfig` | interface | Configuration for an IndexedDB object store |
+| `IndexedDbStore` | class | Generic IndexedDB wrapper with CRUD operations |
 
-Trigger a browser download for the given `Blob` with the specified file name.
+> See [docs/indexed-db-store.md](./docs/indexed-db-store.md) for details.
 
-### DownloadProgress (interface)
+### IndexedDB Virtual FS
 
-```ts
-interface DownloadProgress {
-  receivedLength: number;
-  contentLength: number;
-}
-```
+| API | Type | Description |
+|-----|------|-------------|
+| `VirtualFsEntry` | interface | Entry representing a file or directory in the virtual FS |
+| `IndexedDbVirtualFs` | class | Virtual file system backed by IndexedDB |
 
-### fetchUrlBytes
+> See [docs/indexed-db-virtual-fs.md](./docs/indexed-db-virtual-fs.md) for details.
 
-```ts
-async function fetchUrlBytes(
-  url: string,
-  options?: { onProgress?: (progress: DownloadProgress) => void },
-): Promise<Uint8Array>
-```
+## Usage Examples
 
-Fetch URL content as a `Uint8Array`. Optionally reports download progress via `onProgress`.
+### Copy/Paste with ClipboardEvent
 
-### openFileDialog
+```typescript
+import { copyElement, pasteToElement } from "@simplysm/core-browser";
 
-```ts
-function openFileDialog(options?: {
-  accept?: string;
-  multiple?: boolean;
-}): Promise<File[] | undefined>
+document.addEventListener("copy", (event) => copyElement(event));
+document.addEventListener("paste", (event) => pasteToElement(event));
 ```
 
-Open a native file picker dialog. Returns selected files, or `undefined` if cancelled.
+### Download a Blob
 
-### StoreConfig (interface)
+```typescript
+import { downloadBlob } from "@simplysm/core-browser";
 
-```ts
-interface StoreConfig {
-  name: string;
-  keyPath: string;
-}
+const blob = new Blob(["hello"], { type: "text/plain" });
+downloadBlob(blob, "hello.txt");
 ```
 
-### IndexedDbStore (class)
+### Fetch binary data with progress
 
-IndexedDB wrapper providing simple key-value operations.
+```typescript
+import { fetchUrlBytes } from "@simplysm/core-browser";
 
-**Constructor:**
-
-```ts
-constructor(dbName: string, dbVersion: number, storeConfigs: StoreConfig[])
+const data = await fetchUrlBytes("/api/file.bin", {
+  onProgress: ({ receivedLength, contentLength }) => {
+    console.log(`${receivedLength} / ${contentLength}`);
+  },
+});
 ```
 
-**Methods:**
+### Open a file dialog
 
-| 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 |
+```typescript
+import { openFileDialog } from "@simplysm/core-browser";
 
-### VirtualFsEntry (interface)
-
-```ts
-interface VirtualFsEntry {
-  kind: "file" | "dir";
-  dataBase64?: string;
+const files = await openFileDialog({ accept: ".csv", multiple: true });
+if (files) {
+  for (const file of files) {
+    console.log(file.name);
+  }
 }
 ```
 
-### 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
+### IndexedDB Store
 
-// 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
+```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("items", "1");
+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.4",
+  "version": "14.0.6",
   "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.4"
+    "@simplysm/core-common": "14.0.6"
   }
 }