@simplysm/core-browser 13.0.85 → 13.0.87

package/docs/element-extensions.md

@@ -1,151 +0,0 @@
-# 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

@@ -1,86 +0,0 @@
-# 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

@@ -1,193 +0,0 @@
-# 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

@@ -1,94 +0,0 @@
-# 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
-  }
-}
-```