@fgv/ts-web-extras 5.1.0-0 → 5.1.0-10

package/docs/classes/LocalStorageTreeAccessors.md

@@ -0,0 +1,270 @@
+[Home](../README.md) > LocalStorageTreeAccessors
+
+# Class: LocalStorageTreeAccessors
+
+Browser localStorage-backed file tree accessors with persistence support.
+
+Maps filesystem-like directory paths to localStorage keys, where each key stores
+multiple collections as a JSON object. This provides a general-purpose implementation
+for browser-based file tree persistence without requiring File System Access API.
+
+Storage format per key: `{ "collection-id": "<raw file content>" }`
+File paths map as: `/data/ingredients/collection-id.yaml` → stored in key for `/data/ingredients`
+
+Legacy format (v1): `{ "collection-id": { ...parsedJsonObject } }` is auto-migrated on load.
+
+**Extends:** `InMemoryTreeAccessors<TCT>`
+
+**Implements:** `IPersistentFileTreeAccessors<TCT>`
+
+## Methods
+
+<table><thead><tr><th>
+
+Method
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[fromStorage(params)](./LocalStorageTreeAccessors.fromStorage.md)
+
+</td><td>
+
+`static`
+
+</td><td>
+
+Create LocalStorageTreeAccessors from browser localStorage.
+
+</td></tr>
+<tr><td>
+
+[create(files, prefix)](./LocalStorageTreeAccessors.create.md)
+
+</td><td>
+
+`static`
+
+</td><td>
+
+Creates a new FileTree.InMemoryTreeAccessors | InMemoryTreeAccessors instance with the supplied
+
+</td></tr>
+<tr><td>
+
+[syncToDisk()](./LocalStorageTreeAccessors.syncToDisk.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Sync all dirty files to localStorage.
+
+</td></tr>
+<tr><td>
+
+[isDirty()](./LocalStorageTreeAccessors.isDirty.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Check if there are unsaved changes.
+
+</td></tr>
+<tr><td>
+
+[getDirtyPaths()](./LocalStorageTreeAccessors.getDirtyPaths.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Get list of file paths with unsaved changes.
+
+</td></tr>
+<tr><td>
+
+[deleteFile(path)](./LocalStorageTreeAccessors.deleteFile.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Delete a file and remove it from localStorage.
+
+</td></tr>
+<tr><td>
+
+[saveFileContents(path, contents)](./LocalStorageTreeAccessors.saveFileContents.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Save file contents.
+
+</td></tr>
+<tr><td>
+
+[fileIsMutable(path)](./LocalStorageTreeAccessors.fileIsMutable.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Check if a file is mutable and return persistence detail.
+
+</td></tr>
+<tr><td>
+
+[resolveAbsolutePath(paths)](./LocalStorageTreeAccessors.resolveAbsolutePath.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IFileTreeAccessors.resolveAbsolutePath
+
+</td></tr>
+<tr><td>
+
+[getExtension(path)](./LocalStorageTreeAccessors.getExtension.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IFileTreeAccessors.getExtension
+
+</td></tr>
+<tr><td>
+
+[getBaseName(path, suffix)](./LocalStorageTreeAccessors.getBaseName.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IFileTreeAccessors.getBaseName
+
+</td></tr>
+<tr><td>
+
+[joinPaths(paths)](./LocalStorageTreeAccessors.joinPaths.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IFileTreeAccessors.joinPaths
+
+</td></tr>
+<tr><td>
+
+[getItem(itemPath)](./LocalStorageTreeAccessors.getItem.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IFileTreeAccessors.getItem
+
+</td></tr>
+<tr><td>
+
+[getFileContents(path)](./LocalStorageTreeAccessors.getFileContents.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IFileTreeAccessors.getFileContents
+
+</td></tr>
+<tr><td>
+
+[getFileContentType(path, provided)](./LocalStorageTreeAccessors.getFileContentType.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IFileTreeAccessors.getFileContentType
+
+</td></tr>
+<tr><td>
+
+[getChildren(path)](./LocalStorageTreeAccessors.getChildren.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IFileTreeAccessors.getChildren
+
+</td></tr>
+<tr><td>
+
+[createDirectory(dirPath)](./LocalStorageTreeAccessors.createDirectory.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IMutableFileTreeAccessors.createDirectory
+
+</td></tr>
+<tr><td>
+
+[deleteDirectory(path)](./LocalStorageTreeAccessors.deleteDirectory.md)
+
+</td><td>
+
+
+
+</td><td>
+
+FileTree.IMutableFileTreeAccessors.deleteDirectory
+
+</td></tr>
+</tbody></table>

package/docs/classes/LocalStorageTreeAccessors.saveFileContents.md

@@ -0,0 +1,25 @@
+[Home](../README.md) > [LocalStorageTreeAccessors](./LocalStorageTreeAccessors.md) > saveFileContents
+
+## LocalStorageTreeAccessors.saveFileContents() method
+
+Save file contents. Marks file as dirty and optionally auto-syncs.
+
+**Signature:**
+
+```typescript
+saveFileContents(path: string, contents: string): Result<string>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>path</td><td>string</td><td>File path</td></tr>
+<tr><td>contents</td><td>string</td><td>New file contents</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Result&lt;string&gt;
+
+Result with the saved contents or error

package/docs/classes/LocalStorageTreeAccessors.syncToDisk.md

@@ -0,0 +1,17 @@
+[Home](../README.md) > [LocalStorageTreeAccessors](./LocalStorageTreeAccessors.md) > syncToDisk
+
+## LocalStorageTreeAccessors.syncToDisk() method
+
+Sync all dirty files to localStorage.
+
+**Signature:**
+
+```typescript
+syncToDisk(): Promise<Result<void>>;
+```
+
+**Returns:**
+
+Promise&lt;Result&lt;void&gt;&gt;
+
+Result indicating success or failure

package/docs/functions/createBrowserCryptoProvider.md

@@ -0,0 +1,12 @@
+[Home](../README.md) > createBrowserCryptoProvider
+
+# Function: createBrowserCryptoProvider
+
+Creates a CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider if Web
+Crypto API is available.
+
+## Signature
+
+```typescript
+function createBrowserCryptoProvider(): Result<BrowserCryptoProvider>
+```

package/docs/functions/exportAsJson.md

@@ -0,0 +1,12 @@
+[Home](../README.md) > exportAsJson
+
+# Function: exportAsJson
+
+Export data as JSON file using legacy blob download method.
+Creates a temporary download link and triggers file download.
+
+## Signature
+
+```typescript
+function exportAsJson(data: unknown, filename: string): void
+```

package/docs/functions/exportUsingFileSystemAPI.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > exportUsingFileSystemAPI
+
+# Function: exportUsingFileSystemAPI
+
+Export data using File System Access API with fallback to blob download.
+
+## Signature
+
+```typescript
+function exportUsingFileSystemAPI(data: unknown, suggestedName: string, description: string, window: Window): Promise<boolean>
+```

package/docs/functions/extractDirectoryPath.md

@@ -0,0 +1,13 @@
+[Home](../README.md) > extractDirectoryPath
+
+# Function: extractDirectoryPath
+
+Extracts the directory path from a file or directory path
+If the path appears to be a directory (no extension), returns it as-is
+If the path appears to be a file, returns the parent directory
+
+## Signature
+
+```typescript
+function extractDirectoryPath(path: string): string
+```

package/docs/functions/extractFileListMetadata.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > extractFileListMetadata
+
+# Function: extractFileListMetadata
+
+Helper function to extract metadata from a `FileList`.
+
+## Signature
+
+```typescript
+function extractFileListMetadata(fileList: FileList): IFileMetadata[]
+```

package/docs/functions/extractFileMetadata.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > extractFileMetadata
+
+# Function: extractFileMetadata
+
+Helper function to extract metadata from a `File`.
+
+## Signature
+
+```typescript
+function extractFileMetadata(file: File): IFileMetadata
+```

package/docs/functions/fromDirectoryUpload.md

@@ -0,0 +1,12 @@
+[Home](../README.md) > fromDirectoryUpload
+
+# Function: fromDirectoryUpload
+
+Helper function to create a new FileTree instance
+from a directory upload with webkitRelativePath support.
+
+## Signature
+
+```typescript
+function fromDirectoryUpload(fileList: FileList, params: IFileTreeInitParams<string>): Promise<Result<FileTree_2<string>>>
+```

package/docs/functions/fromFileList.md

@@ -0,0 +1,12 @@
+[Home](../README.md) > fromFileList
+
+# Function: fromFileList
+
+Helper function to create a new FileTree instance
+from a browser FileList (e.g., from input[type="file"]).
+
+## Signature
+
+```typescript
+function fromFileList(fileList: FileList, params: IFileTreeInitParams<string>): Promise<Result<FileTree_2<string>>>
+```

package/docs/functions/getOriginalFile.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > getOriginalFile
+
+# Function: getOriginalFile
+
+Helper function to get the original File object from a FileList by path.
+
+## Signature
+
+```typescript
+function getOriginalFile(fileList: FileList, path: string): Result<File>
+```

package/docs/functions/isDirectoryHandle.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > isDirectoryHandle
+
+# Function: isDirectoryHandle
+
+Type guard to check if a FileSystemHandle is a directory handle
+
+## Signature
+
+```typescript
+function isDirectoryHandle(handle: FileSystemHandle): handle is FileSystemDirectoryHandle
+```

package/docs/functions/isFileHandle.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > isFileHandle
+
+# Function: isFileHandle
+
+Type guard to check if a FileSystemHandle is a file handle
+
+## Signature
+
+```typescript
+function isFileHandle(handle: FileSystemHandle): handle is FileSystemFileHandle
+```

package/docs/functions/isFilePath.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > isFilePath
+
+# Function: isFilePath
+
+Determines if a path appears to be a file (has extension) or directory
+
+## Signature
+
+```typescript
+function isFilePath(path: string): boolean
+```

package/docs/functions/parseContextFilter.md

@@ -0,0 +1,12 @@
+[Home](../README.md) > parseContextFilter
+
+# Function: parseContextFilter
+
+Converts context filter token to context object
+Example: "language=en-US|territory=US" -\> { language: "en-US", territory: "US" }
+
+## Signature
+
+```typescript
+function parseContextFilter(contextFilter: string): Record<string, string>
+```

package/docs/functions/parseQualifierDefaults.md

@@ -0,0 +1,12 @@
+[Home](../README.md) > parseQualifierDefaults
+
+# Function: parseQualifierDefaults
+
+Converts qualifier defaults token to structured format
+Example: "language=en-US,en-CA|territory=US" -\> { language: ["en-US", "en-CA"], territory: ["US"] }
+
+## Signature
+
+```typescript
+function parseQualifierDefaults(qualifierDefaults: string): Record<string, string[]>
+```

package/docs/functions/parseResourceTypes.md

@@ -0,0 +1,12 @@
+[Home](../README.md) > parseResourceTypes
+
+# Function: parseResourceTypes
+
+Converts resource types string to array
+Example: "json,string" -\> ["json", "string"]
+
+## Signature
+
+```typescript
+function parseResourceTypes(resourceTypes: string): string[]
+```

package/docs/functions/parseUrlParameters.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > parseUrlParameters
+
+# Function: parseUrlParameters
+
+Parses URL parameters and extracts configuration options
+
+## Signature
+
+```typescript
+function parseUrlParameters(): IUrlConfigOptions
+```

package/docs/functions/safeShowDirectoryPicker.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > safeShowDirectoryPicker
+
+# Function: safeShowDirectoryPicker
+
+Safely access showDirectoryPicker with proper type checking
+
+## Signature
+
+```typescript
+function safeShowDirectoryPicker(window: Window, options: ShowDirectoryPickerOptions): Promise<FileSystemDirectoryHandle | null>
+```

package/docs/functions/safeShowOpenFilePicker.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > safeShowOpenFilePicker
+
+# Function: safeShowOpenFilePicker
+
+Safely access showOpenFilePicker with proper type checking
+
+## Signature
+
+```typescript
+function safeShowOpenFilePicker(window: Window, options: ShowOpenFilePickerOptions): Promise<FileSystemFileHandle[] | null>
+```

package/docs/functions/safeShowSaveFilePicker.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > safeShowSaveFilePicker
+
+# Function: safeShowSaveFilePicker
+
+Safely access showSaveFilePicker with proper type checking
+
+## Signature
+
+```typescript
+function safeShowSaveFilePicker(window: Window, options: ShowSaveFilePickerOptions): Promise<FileSystemFileHandle | null>
+```

package/docs/functions/supportsFileSystemAccess.md

@@ -0,0 +1,11 @@
+[Home](../README.md) > supportsFileSystemAccess
+
+# Function: supportsFileSystemAccess
+
+Type guard to check if the browser supports the File System Access API
+
+## Signature
+
+```typescript
+function supportsFileSystemAccess(window: Window): window is WindowWithFsAccess
+```

package/docs/interfaces/FilePickerAcceptType.accept.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > [FilePickerAcceptType](./FilePickerAcceptType.md) > accept
+
+## FilePickerAcceptType.accept property
+
+**Signature:**
+
+```typescript
+accept: Record<string, string | string[]>;
+```

package/docs/interfaces/FilePickerAcceptType.description.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > [FilePickerAcceptType](./FilePickerAcceptType.md) > description
+
+## FilePickerAcceptType.description property
+
+**Signature:**
+
+```typescript
+description: string;
+```

package/docs/interfaces/FilePickerAcceptType.md

@@ -0,0 +1,61 @@
+[Home](../README.md) > FilePickerAcceptType
+
+# Interface: FilePickerAcceptType
+
+File picker accept type
+
+## Properties
+
+<table><thead><tr><th>
+
+Property
+
+</th><th>
+
+Modifiers
+
+</th><th>
+
+Type
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[description](./FilePickerAcceptType.description.md)
+
+</td><td>
+
+
+
+</td><td>
+
+string
+
+</td><td>
+
+
+
+</td></tr>
+<tr><td>
+
+[accept](./FilePickerAcceptType.accept.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Record&lt;string, string | string[]&gt;
+
+</td><td>
+
+
+
+</td></tr>
+</tbody></table>

package/docs/interfaces/FileSystemCreateWritableOptions.keepExistingData.md

@@ -0,0 +1,9 @@
+[Home](../README.md) > [FileSystemCreateWritableOptions](./FileSystemCreateWritableOptions.md) > keepExistingData
+
+## FileSystemCreateWritableOptions.keepExistingData property
+
+**Signature:**
+
+```typescript
+keepExistingData: boolean;
+```