@simplysm/core-browser 13.0.97 → 13.0.99

package/README.md

@@ -0,0 +1,106 @@
+# @simplysm/core-browser
+
+Simplysm package - Core module (browser). Browser-only utilities including DOM extensions, file downloads, IndexedDB storage, and virtual file system.
+
+## Installation
+
+```bash
+npm install @simplysm/core-browser
+```
+
+## Side-Effect Imports
+
+This package includes side-effect imports that augment global prototypes when the module is loaded:
+
+- `Element.prototype` -- Adds `findAll`, `findFirst`, `prependChild`, `getParents`, `findFocusableParent`, `findFirstFocusableChild`, `isOffsetElement`, `isVisible`.
+- `HTMLElement.prototype` -- Adds `repaint`, `getRelativeOffset`, `scrollIntoViewIfNeeded`.
+
+These side effects run automatically when you import from `@simplysm/core-browser`.
+
+## API Overview
+
+### Element Extensions
+
+| 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 |
+
+-> See [docs/element-extensions.md](./docs/element-extensions.md) for details.
+
+### HTMLElement Extensions
+
+| 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 |
+
+-> See [docs/html-element-extensions.md](./docs/html-element-extensions.md) for details.
+
+### Utilities
+
+| 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 |
+
+-> See [docs/utilities.md](./docs/utilities.md) for details.
+
+### Classes
+
+| 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 |
+
+-> See [docs/classes.md](./docs/classes.md) for details.
+
+## Usage Examples
+
+### Download a file
+
+```typescript
+import { downloadBlob } from "@simplysm/core-browser";
+
+const blob = new Blob(["Hello"], { type: "text/plain" });
+downloadBlob(blob, "hello.txt");
+```
+
+### Open file dialog and read files
+
+```typescript
+import { openFileDialog } from "@simplysm/core-browser";
+
+const files = await openFileDialog({ accept: ".csv", multiple: true });
+if (files) {
+  for (const file of files) {
+    const text = await file.text();
+  }
+}
+```
+
+### Use IndexedDB store
+
+```typescript
+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");
+store.close();
+```

package/docs/classes.md

@@ -0,0 +1,184 @@
+# Classes
+
+IndexedDB-based storage classes for browser-side data persistence.
+
+```typescript
+import { IndexedDbStore, IndexedDbVirtualFs } from "@simplysm/core-browser";
+```
+
+## `StoreConfig`
+
+Configuration for an IndexedDB object store.
+
+```typescript
+interface StoreConfig {
+  name: string;
+  keyPath: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Object store name |
+| `keyPath` | `string` | Key path for the object store |
+
+## `IndexedDbStore`
+
+IndexedDB wrapper that manages database connections, schema upgrades, and transactional CRUD operations. Handles version changes and connection blocking gracefully.
+
+### Constructor
+
+```typescript
+constructor(dbName: string, dbVersion: number, storeConfigs: StoreConfig[])
+```
+
+**Parameters:**
+- `dbName` -- Database name
+- `dbVersion` -- Database version (triggers upgrade when increased)
+- `storeConfigs` -- Array of object store configurations
+
+### Methods
+
+#### `open`
+
+Open or reuse the database connection. Creates object stores defined in `storeConfigs` during upgrade. Handles `onversionchange` and `onclose` events to clear internal references.
+
+```typescript
+async open(): Promise<IDBDatabase>;
+```
+
+#### `withStore`
+
+Execute a function within an IndexedDB transaction. Handles transaction completion and error propagation.
+
+```typescript
+async withStore<TResult>(
+  storeName: string,
+  mode: IDBTransactionMode,
+  fn: (store: IDBObjectStore) => Promise<TResult>,
+): Promise<TResult>;
+```
+
+#### `get`
+
+Get a value by key from a store.
+
+```typescript
+async get<TValue>(storeName: string, key: IDBValidKey): Promise<TValue | undefined>;
+```
+
+#### `put`
+
+Put a value into a store (insert or update).
+
+```typescript
+async put(storeName: string, value: unknown): Promise<void>;
+```
+
+#### `delete`
+
+Delete a value by key from a store.
+
+```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 and clear internal references.
+
+```typescript
+close(): void;
+```
+
+---
+
+## `VirtualFsEntry`
+
+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 (files only) |
+
+## `IndexedDbVirtualFs`
+
+Virtual file system backed by IndexedDB. Stores files and directories as key-value entries with hierarchical path support. Built on top of `IndexedDbStore`.
+
+### Constructor
+
+```typescript
+constructor(db: IndexedDbStore, storeName: string, keyField: string)
+```
+
+**Parameters:**
+- `db` -- `IndexedDbStore` instance
+- `storeName` -- Name of the object store to use
+- `keyField` -- Key field name for entries
+
+### Methods
+
+#### `getEntry`
+
+Get a virtual file system entry by its full key.
+
+```typescript
+async getEntry(fullKey: string): Promise<VirtualFsEntry | undefined>;
+```
+
+#### `putEntry`
+
+Put an entry into the virtual file system.
+
+```typescript
+async putEntry(fullKey: string, kind: "file" | "dir", dataBase64?: string): Promise<void>;
+```
+
+#### `deleteByPrefix`
+
+Delete all entries matching a key prefix (the entry with the exact prefix key and all children).
+
+```typescript
+async deleteByPrefix(keyPrefix: string): Promise<boolean>;
+```
+
+**Returns:** `true` if any entries were deleted.
+
+#### `listChildren`
+
+List immediate children under a prefix path.
+
+```typescript
+async listChildren(prefix: string): Promise<{ name: string; isDirectory: boolean }[]>;
+```
+
+#### `ensureDir`
+
+Ensure a directory path exists by creating all missing parent directories.
+
+```typescript
+async ensureDir(
+  fullKeyBuilder: (path: string) => string,
+  dirPath: string,
+): Promise<void>;
+```
+
+**Parameters:**
+- `fullKeyBuilder` -- Function to convert a path segment to a full key
+- `dirPath` -- Directory path to ensure (e.g., `"/a/b/c"`)

package/docs/element-extensions.md

@@ -0,0 +1,134 @@
+# Element Extensions
+
+Extensions added to the `Element.prototype` via side-effect import. These methods are available on all `Element` instances when `@simplysm/core-browser` is imported.
+
+```typescript
+import "@simplysm/core-browser";
+```
+
+## `ElementBounds`
+
+Element bounds information type returned by `getBounds`.
+
+```typescript
+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;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `Element` | Element to be measured |
+| `top` | `number` | Top position relative to viewport |
+| `left` | `number` | Left position relative to viewport |
+| `width` | `number` | Element width |
+| `height` | `number` | Element height |
+
+## `Element.findAll`
+
+Find all child elements matching a CSS selector.
+
+```typescript
+findAll<TEl extends Element = Element>(selector: string): TEl[];
+```
+
+Returns an empty array if the selector is empty.
+
+## `Element.findFirst`
+
+Find first element matching a CSS selector.
+
+```typescript
+findFirst<TEl extends Element = Element>(selector: string): TEl | undefined;
+```
+
+Returns `undefined` if the selector is empty or no match is found.
+
+## `Element.prependChild`
+
+Insert element as first child.
+
+```typescript
+prependChild<TEl extends Element>(child: TEl): TEl;
+```
+
+## `Element.getParents`
+
+Get all parent elements in order of proximity (from closest to farthest).
+
+```typescript
+getParents(): Element[];
+```
+
+## `Element.findFocusableParent`
+
+Find first focusable parent element (using tabbable library).
+
+```typescript
+findFocusableParent(): HTMLElement | undefined;
+```
+
+## `Element.findFirstFocusableChild`
+
+Find first focusable child element (using tabbable library). Uses a TreeWalker for traversal.
+
+```typescript
+findFirstFocusableChild(): HTMLElement | undefined;
+```
+
+## `Element.isOffsetElement`
+
+Check if element is an offset parent (`position: relative | absolute | fixed | sticky`).
+
+```typescript
+isOffsetElement(): boolean;
+```
+
+## `Element.isVisible`
+
+Check if element is visible on screen. Checks existence of clientRects, `visibility: hidden`, and `opacity: 0`.
+
+```typescript
+isVisible(): boolean;
+```
+
+## `copyElement`
+
+Copy element content to clipboard. Use as a copy event handler. Finds the first `input`/`textarea` within the target element and copies its value.
+
+```typescript
+function copyElement(event: ClipboardEvent): void;
+```
+
+## `pasteToElement`
+
+Paste clipboard content to element. Use as a paste event handler. Finds the first `input`/`textarea` within the target element and replaces its entire value with clipboard content. Does not consider cursor position or selection.
+
+```typescript
+function pasteToElement(event: ClipboardEvent): void;
+```
+
+## `getBounds`
+
+Get bounds information for multiple elements using IntersectionObserver.
+
+```typescript
+async function getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>;
+```
+
+**Parameters:**
+- `els` -- Array of target elements
+- `timeout` -- Timeout in milliseconds (default: `5000`)
+
+**Throws:** `TimeoutError` if no response within the timeout duration.
+
+Results are returned sorted in input order, with duplicates removed.

package/docs/html-element-extensions.md

@@ -0,0 +1,56 @@
+# HTMLElement Extensions
+
+Extensions added to the `HTMLElement.prototype` via side-effect import. These methods are available on all `HTMLElement` instances when `@simplysm/core-browser` is imported.
+
+```typescript
+import "@simplysm/core-browser";
+```
+
+## `HTMLElement.repaint`
+
+Force repaint by triggering reflow. Internally accesses `offsetHeight` which triggers forced synchronous layout in the browser.
+
+```typescript
+repaint(): void;
+```
+
+## `HTMLElement.getRelativeOffset`
+
+Calculate relative position based on a parent element for CSS positioning.
+
+```typescript
+getRelativeOffset(parent: HTMLElement | string): { top: number; left: number };
+```
+
+Returns document-based coordinates including `window.scrollX/Y` that can be directly used in CSS `top`/`left` properties.
+
+**Parameters:**
+- `parent` -- Parent element or CSS selector to use as reference (e.g., `document.body`, `".container"`)
+
+**Throws:** `ArgumentError` if parent element cannot be found.
+
+**Factors included in calculation:**
+- Viewport-relative position (`getBoundingClientRect`)
+- Document scroll position (`window.scrollX/Y`)
+- Parent element internal scroll (`parentEl.scrollTop/Left`)
+- Border thickness of intermediate elements
+- CSS transform transformations
+
+**Common use cases:**
+- Position dropdowns, popups after appending to `document.body`
+- Works correctly on scrolled pages
+
+## `HTMLElement.scrollIntoViewIfNeeded`
+
+Scroll to make target visible if hidden by offset area (e.g., fixed header/column). Only handles cases where target extends beyond top/left boundaries of the scroll area. For downward/rightward scrolling, relies on browser's default focus scroll behavior. Typically used with focus events on tables with fixed headers or columns.
+
+```typescript
+scrollIntoViewIfNeeded(
+  target: { top: number; left: number },
+  offset?: { top: number; left: number },
+): void;
+```
+
+**Parameters:**
+- `target` -- Target position within container (`offsetTop`, `offsetLeft`)
+- `offset` -- Size of area that must not be obscured (e.g., fixed header height, fixed column width). Defaults to `{ top: 0, left: 0 }`.

package/docs/utilities.md

@@ -0,0 +1,71 @@
+# Utilities
+
+Standalone utility functions for browser-side operations.
+
+```typescript
+import { downloadBlob, fetchUrlBytes, openFileDialog } from "@simplysm/core-browser";
+```
+
+## `downloadBlob`
+
+Download a Blob as a file by creating a temporary object URL and clicking a hidden link.
+
+```typescript
+function downloadBlob(blob: Blob, fileName: string): void;
+```
+
+**Parameters:**
+- `blob` -- Blob object to download
+- `fileName` -- File name to save as
+
+## `DownloadProgress`
+
+Download progress information used by `fetchUrlBytes`.
+
+```typescript
+interface DownloadProgress {
+  receivedLength: number;
+  contentLength: number;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `receivedLength` | `number` | Number of bytes received so far |
+| `contentLength` | `number` | Total content length from `Content-Length` header |
+
+## `fetchUrlBytes`
+
+Download binary data from a URL with optional progress callback support.
+
+```typescript
+async function fetchUrlBytes(
+  url: string,
+  options?: { onProgress?: (progress: DownloadProgress) => void },
+): Promise<Uint8Array>;
+```
+
+**Parameters:**
+- `url` -- URL to download from
+- `options.onProgress` -- Progress callback function
+
+When `Content-Length` is known, pre-allocates memory for efficiency. For chunked encoding (unknown length), collects chunks and merges them.
+
+**Throws:** `Error` if the download fails or the response body is not readable.
+
+## `openFileDialog`
+
+Programmatically open a file selection dialog.
+
+```typescript
+function openFileDialog(options?: {
+  accept?: string;
+  multiple?: boolean;
+}): Promise<File[] | undefined>;
+```
+
+**Parameters:**
+- `options.accept` -- File type filter (e.g., `".csv"`, `"image/*"`)
+- `options.multiple` -- Allow multiple file selection (default: `false`)
+
+**Returns:** Array of selected files, or `undefined` if the dialog is cancelled.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-browser",
-  "version": "13.0.97",
+  "version": "13.0.99",
   "description": "Simplysm package - Core module (browser)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -24,7 +24,7 @@
   ],
   "dependencies": {
     "tabbable": "^6.4.0",
-    "@simplysm/core-common": "13.0.97"
+    "@simplysm/core-common": "13.0.99"
   },
   "devDependencies": {
     "happy-dom": "^20.8.4"