@simplysm/core-browser 13.0.82 → 13.0.83

package/README.md

@@ -0,0 +1,29 @@
+# @simplysm/core-browser
+
+> Simplysm package - Core module (browser)
+
+Browser-specific utilities for DOM manipulation, file handling, HTTP fetching, and IndexedDB storage. This package extends native `Element` and `HTMLElement` prototypes with convenience methods and provides standalone utility functions for common browser tasks.
+
+## Installation
+
+```bash
+npm install @simplysm/core-browser
+```
+
+**Peer dependency:** `@simplysm/core-common`
+
+## Side Effects
+
+This package includes side-effect imports that augment global prototypes. The following modules execute on import:
+
+- `extensions/element-ext` -- extends `Element.prototype`
+- `extensions/html-element-ext` -- extends `HTMLElement.prototype`
+
+## Documentation
+
+| Category | Description | File |
+|----------|-------------|------|
+| Element Extensions | `Element` prototype methods and clipboard/bounds helpers | [docs/element-extensions.md](docs/element-extensions.md) |
+| HTMLElement Extensions | `HTMLElement` prototype methods for layout and scrolling | [docs/html-element-extensions.md](docs/html-element-extensions.md) |
+| Utilities | File download, fetch with progress, file dialog | [docs/utilities.md](docs/utilities.md) |
+| IndexedDB | IndexedDB store wrapper and virtual filesystem | [docs/indexed-db.md](docs/indexed-db.md) |

package/docs/element-extensions.md

@@ -0,0 +1,151 @@
+# Element Extensions
+
+Side-effect module that extends `Element.prototype` with DOM traversal, focus management, and visibility helpers. Also exports standalone functions for clipboard operations and element bounds measurement.
+
+## Prototype Methods
+
+### Element.findAll
+
+```typescript
+findAll<TEl extends Element = Element>(selector: string): TEl[]
+```
+
+Find all child elements matching a CSS selector. Returns an empty array if the selector is empty.
+
+### Element.findFirst
+
+```typescript
+findFirst<TEl extends Element = Element>(selector: string): TEl | undefined
+```
+
+Find the first child element matching a CSS selector. Returns `undefined` if the selector is empty or no match is found.
+
+### Element.prependChild
+
+```typescript
+prependChild<TEl extends Element>(child: TEl): TEl
+```
+
+Insert an element as the first child. Returns the inserted child element.
+
+### Element.getParents
+
+```typescript
+getParents(): Element[]
+```
+
+Get all parent elements ordered from closest to farthest (up to the root).
+
+### Element.findFocusableParent
+
+```typescript
+findFocusableParent(): HTMLElement | undefined
+```
+
+Find the nearest focusable ancestor element. Uses the `tabbable` library to determine focusability.
+
+### Element.findFirstFocusableChild
+
+```typescript
+findFirstFocusableChild(): HTMLElement | undefined
+```
+
+Find the first focusable descendant element using a tree walker. Uses the `tabbable` library to determine focusability.
+
+### Element.isOffsetElement
+
+```typescript
+isOffsetElement(): boolean
+```
+
+Check whether the element is an offset parent. Returns `true` if the computed `position` is `relative`, `absolute`, `fixed`, or `sticky`.
+
+### Element.isVisible
+
+```typescript
+isVisible(): boolean
+```
+
+Check whether the element is visible on screen. Checks for the existence of client rects, `visibility: hidden`, and `opacity: 0`.
+
+---
+
+## Exported Interfaces
+
+### ElementBounds
+
+```typescript
+interface ElementBounds {
+  target: Element;
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+```
+
+Bounds information for an element, with positions relative to the viewport.
+
+---
+
+## Exported Functions
+
+### copyElement
+
+```typescript
+function copyElement(event: ClipboardEvent): void
+```
+
+Copy element content to clipboard. Intended for use as a `copy` event handler. Finds the first `input` or `textarea` within the event target and writes its value to the clipboard.
+
+### pasteToElement
+
+```typescript
+function pasteToElement(event: ClipboardEvent): void
+```
+
+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 value with clipboard text, dispatching an `input` event afterward.
+
+### getBounds
+
+```typescript
+function getBounds(els: Element[], timeout?: number): Promise<ElementBounds[]>
+```
+
+Get bounds information for multiple elements using `IntersectionObserver`. Results are returned in the same order as the input array, with duplicates removed.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `els` | `Element[]` | -- | Target elements |
+| `timeout` | `number` | `5000` | Timeout in milliseconds |
+
+Throws `TimeoutError` (from `@simplysm/core-common`) if the observer does not respond within the timeout duration.
+
+---
+
+## Usage Examples
+
+```typescript
+import "@simplysm/core-browser"; // activate side effects
+
+// Find elements
+const buttons = container.findAll<HTMLButtonElement>("button.primary");
+const firstInput = form.findFirst<HTMLInputElement>("input[type=text]");
+
+// DOM traversal
+const parents = element.getParents();
+const focusable = element.findFirstFocusableChild();
+
+// Visibility check
+if (element.isVisible()) {
+  // element is rendered and visible
+}
+
+// Clipboard handlers
+document.addEventListener("copy", copyElement);
+document.addEventListener("paste", pasteToElement);
+
+// Measure element bounds
+const bounds = await getBounds([el1, el2, el3]);
+// bounds[0].top, bounds[0].left, bounds[0].width, bounds[0].height
+```

package/docs/html-element-extensions.md

@@ -0,0 +1,86 @@
+# HTMLElement Extensions
+
+Side-effect module that extends `HTMLElement.prototype` with layout and scrolling utilities.
+
+## Prototype Methods
+
+### HTMLElement.repaint
+
+```typescript
+repaint(): void
+```
+
+Force a synchronous repaint by triggering a reflow. Internally accesses `offsetHeight` to flush pending style changes.
+
+---
+
+### HTMLElement.getRelativeOffset
+
+```typescript
+getRelativeOffset(parent: HTMLElement | string): { top: number; left: number }
+```
+
+Calculate the element's position relative to a parent element, returning document-based coordinates suitable for CSS `top`/`left` properties.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `parent` | `HTMLElement \| string` | Parent element or CSS selector to use as reference |
+
+**Returns:** `{ top: number; left: number }` -- coordinates usable in CSS positioning.
+
+**Throws:** `ArgumentError` (from `@simplysm/core-common`) if the parent element cannot be found.
+
+The calculation accounts for:
+- 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 include positioning dropdowns and popups after appending them to `document.body`.
+
+---
+
+### HTMLElement.scrollIntoViewIfNeeded
+
+```typescript
+scrollIntoViewIfNeeded(
+  target: { top: number; left: number },
+  offset?: { top: number; left: number },
+): void
+```
+
+Scroll the element so that a target position is not obscured by a fixed offset area (e.g., a sticky header or fixed column).
+
+| 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 area that must remain unobscured |
+
+Only handles cases where the target extends beyond the top/left boundaries of the scroll area. For downward/rightward scrolling, the browser's default focus scroll behavior is relied upon. Typically used with focus events on tables that have fixed headers or columns.
+
+---
+
+## Usage Examples
+
+```typescript
+import "@simplysm/core-browser"; // activate side effects
+
+// Force repaint after style changes
+element.style.transform = "scale(1.1)";
+element.repaint();
+
+// Position a dropdown relative to document.body
+const pos = trigger.getRelativeOffset(document.body);
+dropdown.style.top = `${pos.top + trigger.offsetHeight}px`;
+dropdown.style.left = `${pos.left}px`;
+
+// Position relative to a container found by selector
+const pos2 = cell.getRelativeOffset(".scroll-container");
+
+// Scroll table so focused cell is visible past fixed header
+tableContainer.scrollIntoViewIfNeeded(
+  { top: cell.offsetTop, left: cell.offsetLeft },
+  { top: headerHeight, left: fixedColumnWidth },
+);
+```

package/docs/indexed-db.md

@@ -0,0 +1,193 @@
+# IndexedDB
+
+Lightweight wrappers around the browser IndexedDB API. `IndexedDbStore` provides a simplified interface for opening databases and performing CRUD operations. `IndexedDbVirtualFs` builds on top of it to implement a virtual filesystem stored in IndexedDB.
+
+## IndexedDbStore
+
+```typescript
+class IndexedDbStore {
+  constructor(dbName: string, dbVersion: number, storeConfigs: StoreConfig[]);
+}
+```
+
+A wrapper that manages an IndexedDB database with automatic store creation on version upgrades.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dbName` | `string` | Database name |
+| `dbVersion` | `number` | Database version (triggers `onupgradeneeded` when increased) |
+| `storeConfigs` | `StoreConfig[]` | Object store definitions |
+
+### StoreConfig
+
+```typescript
+interface StoreConfig {
+  name: string;
+  keyPath: string;
+}
+```
+
+### Methods
+
+#### open
+
+```typescript
+open(): Promise<IDBDatabase>
+```
+
+Open the database, creating any missing object stores defined in `storeConfigs`. Rejects if the database is blocked by another connection.
+
+#### withStore
+
+```typescript
+withStore<TResult>(
+  storeName: string,
+  mode: IDBTransactionMode,
+  fn: (store: IDBObjectStore) => Promise<TResult>,
+): Promise<TResult>
+```
+
+Execute a callback within a transaction on the specified store. The database connection is automatically opened and closed. If the callback throws, the transaction is aborted.
+
+#### get
+
+```typescript
+get<TValue>(storeName: string, key: IDBValidKey): Promise<TValue | undefined>
+```
+
+Retrieve a single record by key. Returns `undefined` if not found.
+
+#### put
+
+```typescript
+put(storeName: string, value: unknown): Promise<void>
+```
+
+Insert or update a record. The key is extracted from the value using the store's `keyPath`.
+
+#### getAll
+
+```typescript
+getAll<TItem>(storeName: string): Promise<TItem[]>
+```
+
+Retrieve all records from a store.
+
+---
+
+## IndexedDbVirtualFs
+
+```typescript
+class IndexedDbVirtualFs {
+  constructor(db: IndexedDbStore, storeName: string, keyField: string);
+}
+```
+
+A virtual filesystem built on `IndexedDbStore`. Each entry is stored as a record with a full path key, a kind (`"file"` or `"dir"`), and optional Base64-encoded data.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `db` | `IndexedDbStore` | The underlying IndexedDB store instance |
+| `storeName` | `string` | Name of the object store to use |
+| `keyField` | `string` | The key property name in stored records |
+
+### VirtualFsEntry
+
+```typescript
+interface VirtualFsEntry {
+  kind: "file" | "dir";
+  dataBase64?: string;
+}
+```
+
+### Methods
+
+#### getEntry
+
+```typescript
+getEntry(fullKey: string): Promise<VirtualFsEntry | undefined>
+```
+
+Get a single filesystem entry by its full key path.
+
+#### putEntry
+
+```typescript
+putEntry(fullKey: string, kind: "file" | "dir", dataBase64?: string): Promise<void>
+```
+
+Create or update a filesystem entry.
+
+#### deleteByPrefix
+
+```typescript
+deleteByPrefix(keyPrefix: string): Promise<boolean>
+```
+
+Delete all entries whose key matches the prefix or starts with `prefix + "/"`. Returns `true` if any entries were deleted.
+
+#### listChildren
+
+```typescript
+listChildren(prefix: string): Promise<{ name: string; isDirectory: boolean }[]>
+```
+
+List immediate children under a path prefix. Returns each child's name and whether it is a directory.
+
+#### ensureDir
+
+```typescript
+ensureDir(
+  fullKeyBuilder: (path: string) => string,
+  dirPath: string,
+): Promise<void>
+```
+
+Ensure that a directory and all its ancestor directories exist. Walks through each segment of `dirPath` and creates missing directory entries.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fullKeyBuilder` | `(path: string) => string` | Function to convert a path into a full key |
+| `dirPath` | `string` | Directory path to ensure (e.g., `"/data/images"`) |
+
+---
+
+## Usage Examples
+
+```typescript
+import { IndexedDbStore, IndexedDbVirtualFs } from "@simplysm/core-browser";
+
+// Set up a database with one store
+const store = new IndexedDbStore("my-app-db", 1, [
+  { name: "files", keyPath: "path" },
+]);
+
+// Basic CRUD
+await store.put("files", { path: "/config.json", data: "{}" });
+const record = await store.get<{ path: string; data: string }>("files", "/config.json");
+const allRecords = await store.getAll("files");
+
+// Use withStore for custom transactions
+await store.withStore("files", "readwrite", async (objStore) => {
+  return new Promise((resolve, reject) => {
+    const req = objStore.delete("/old-file.txt");
+    req.onsuccess = () => resolve(undefined);
+    req.onerror = () => reject(req.error);
+  });
+});
+
+// Virtual filesystem
+const vfs = new IndexedDbVirtualFs(store, "files", "path");
+
+await vfs.ensureDir((p) => p, "/data/images");
+await vfs.putEntry("/data/images/photo.png", "file", btoa("...binary data..."));
+
+const children = await vfs.listChildren("/data/");
+// [{ name: "images", isDirectory: true }]
+
+const entry = await vfs.getEntry("/data/images/photo.png");
+// { kind: "file", dataBase64: "..." }
+
+const deleted = await vfs.deleteByPrefix("/data/images");
+// true
+```

package/docs/utilities.md

@@ -0,0 +1,94 @@
+# Utilities
+
+Standalone utility functions for file downloads, HTTP fetching with progress tracking, and programmatic file selection dialogs.
+
+## downloadBlob
+
+```typescript
+function downloadBlob(blob: Blob, fileName: string): void
+```
+
+Download a Blob as a file. Creates a temporary object URL, triggers a download via an anchor click, and revokes the URL after 1 second.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `blob` | `Blob` | Blob object to download |
+| `fileName` | `string` | File name for the downloaded file |
+
+---
+
+## fetchUrlBytes
+
+```typescript
+function fetchUrlBytes(
+  url: string,
+  options?: { onProgress?: (progress: DownloadProgress) => void },
+): Promise<Uint8Array>
+```
+
+Download binary data from a URL as a `Uint8Array`, with optional progress reporting.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | URL to download from |
+| `options.onProgress` | `(progress: DownloadProgress) => void` | Callback invoked as chunks are received |
+
+When the server provides a `Content-Length` header, memory is pre-allocated for efficiency. For chunked transfers without `Content-Length`, chunks are collected and concatenated at the end.
+
+Throws an `Error` if the response status is not OK or the response body is not readable.
+
+### DownloadProgress
+
+```typescript
+interface DownloadProgress {
+  receivedLength: number;
+  contentLength: number;
+}
+```
+
+---
+
+## openFileDialog
+
+```typescript
+function openFileDialog(options?: {
+  accept?: string;
+  multiple?: boolean;
+}): Promise<File[] | undefined>
+```
+
+Programmatically open a file selection dialog without requiring a visible `<input type="file">` in the DOM.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `options.accept` | `string` | -- | Accepted file types (e.g., `".png,.jpg"`, `"image/*"`) |
+| `options.multiple` | `boolean` | `false` | Allow selecting multiple files |
+
+**Returns:** A `File[]` if the user selected files, or `undefined` if the dialog was cancelled.
+
+---
+
+## Usage Examples
+
+```typescript
+import { downloadBlob, fetchUrlBytes, openFileDialog } from "@simplysm/core-browser";
+
+// Download a text file
+const blob = new Blob(["Hello, world!"], { type: "text/plain" });
+downloadBlob(blob, "hello.txt");
+
+// Fetch binary data with progress
+const data = await fetchUrlBytes("https://example.com/archive.zip", {
+  onProgress: ({ receivedLength, contentLength }) => {
+    console.log(`${Math.round((receivedLength / contentLength) * 100)}%`);
+  },
+});
+
+// Open file dialog for images
+const files = await openFileDialog({ accept: "image/*", multiple: true });
+if (files) {
+  for (const file of files) {
+    // process each selected file
+  }
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/core-browser",
-  "version": "13.0.82",
+  "version": "13.0.83",
   "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.82"
+    "@simplysm/core-common": "13.0.83"
   },
   "devDependencies": {
     "happy-dom": "^20.8.3"