@private.me/xbind 1.2.0

package/dist-standalone/_deps/ux-helpers/errors.js

@@ -0,0 +1,253 @@
+/**
+ * Error Formatter
+ *
+ * Provides consistent error formatting across all PRIVATE.ME packages.
+ */
+/**
+ * Create a detailed ACI error.
+ *
+ * @param code Machine-readable error code (e.g., 'INVALID_DID')
+ * @param message Human-readable error message
+ * @param options Optional error details (hint, field, docs)
+ * @returns Detailed error object
+ *
+ * @example
+ * ```typescript
+ * const error = createDetailedError(
+ *   'INVALID_DID',
+ *   'DID format is invalid',
+ *   {
+ *     hint: 'DIDs must start with "did:" followed by method (e.g., did:key:z6Mk...)',
+ *     field: 'recipientDID',
+ *     docs: 'https://private.me/docs/did-format'
+ *   }
+ * );
+ * ```
+ */
+export function createDetailedError(code, message, options) {
+    return {
+        code,
+        message,
+        hint: options?.hint,
+        suggested_action: options?.suggested_action,
+        field: options?.field,
+        docs: options?.docs,
+        severity: options?.severity,
+    };
+}
+/**
+ * Format an error for display to the user.
+ *
+ * Creates a human-friendly error message with hints and documentation links.
+ *
+ * @param error Detailed error object
+ * @returns Formatted error string
+ *
+ * @deprecated Use formatErrorStructured() for new code. This function remains for backward compatibility.
+ *
+ * @example
+ * ```typescript
+ * const error = createDetailedError('INVALID_DID', 'DID format is invalid', {
+ *   hint: 'DIDs must start with "did:"',
+ *   docs: 'https://private.me/docs/did-format'
+ * });
+ *
+ * const formatted = formatErrorForUser(error);
+ * // "DID format is invalid
+ * //  Hint: DIDs must start with "did:"
+ * //  Docs: https://private.me/docs/did-format"
+ * ```
+ */
+export function formatErrorForUser(error) {
+    const parts = [error.message];
+    if (error.field) {
+        parts.push(`Field: ${error.field}`);
+    }
+    if (error.hint) {
+        parts.push(`Hint: ${error.hint}`);
+    }
+    if (error.docs) {
+        parts.push(`Docs: ${error.docs}`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Format an error for logging (includes error code).
+ *
+ * @param error Detailed error object
+ * @returns Formatted log string
+ */
+export function formatErrorForLog(error) {
+    const parts = [`[${error.code}] ${error.message}`];
+    if (error.field) {
+        parts.push(`field=${error.field}`);
+    }
+    if (error.hint) {
+        parts.push(`hint="${error.hint}"`);
+    }
+    if (error.docs) {
+        parts.push(`docs=${error.docs}`);
+    }
+    return parts.join(' | ');
+}
+/**
+ * Check if an error is an ACIErrorDetail.
+ *
+ * @param error Unknown error object
+ * @returns True if error is an ACIErrorDetail
+ */
+export function isACIError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const e = error;
+    return (typeof e.code === 'string' &&
+        typeof e.message === 'string' &&
+        (e.hint === undefined || typeof e.hint === 'string') &&
+        (e.field === undefined || typeof e.field === 'string') &&
+        (e.docs === undefined || typeof e.docs === 'string'));
+}
+/**
+ * Convert any error to an ACIErrorDetail.
+ *
+ * @param error Error object (Error, ACIErrorDetail, or unknown)
+ * @returns ACIErrorDetail
+ */
+export function toACIError(error) {
+    // Already an ACI error
+    if (isACIError(error)) {
+        return error;
+    }
+    // Standard Error object
+    if (error instanceof Error) {
+        return {
+            code: 'INTERNAL_ERROR',
+            message: error.message,
+            hint: 'An unexpected error occurred',
+        };
+    }
+    // Unknown error type
+    return {
+        code: 'UNKNOWN_ERROR',
+        message: String(error),
+        hint: 'An unexpected error occurred',
+    };
+}
+/**
+ * Format an error with multiple structured representations.
+ *
+ * Returns an object with the original error details plus formatted versions
+ * optimized for different use cases (display, logging, APIs, docs).
+ *
+ * @param error Detailed error object
+ * @returns Error with formats
+ *
+ * @example
+ * ```typescript
+ * const error = createDetailedError('INVALID_DID', 'DID format is invalid', {
+ *   hint: 'DIDs must start with "did:"',
+ *   field: 'recipientDID',
+ *   docs: 'https://private.me/docs/did-format'
+ * });
+ *
+ * const formatted = formatErrorStructured(error);
+ * console.log(formatted.formats.singleline);
+ * // "error | INVALID_DID | DID format is invalid | field=recipientDID"
+ *
+ * console.log(formatted.formats.multiline);
+ * // "Error: DID format is invalid
+ * //  Code: INVALID_DID
+ * //  Field: recipientDID
+ * //  Hint: DIDs must start with "did:"
+ * //  Docs: https://private.me/docs/did-format"
+ *
+ * console.log(formatted.formats.json);
+ * // '{"code":"INVALID_DID","message":"DID format is invalid",...}'
+ * ```
+ */
+export function formatErrorStructured(error) {
+    // Build multiline format (human display)
+    const multilineParts = [`Error: ${error.message}`, `Code: ${error.code}`];
+    if (error.severity)
+        multilineParts.push(`Severity: ${error.severity}`);
+    if (error.field)
+        multilineParts.push(`Field: ${error.field}`);
+    if (error.hint)
+        multilineParts.push(`Hint: ${error.hint}`);
+    if (error.suggested_action)
+        multilineParts.push(`Action: ${error.suggested_action}`);
+    if (error.docs)
+        multilineParts.push(`Docs: ${error.docs}`);
+    const multiline = multilineParts.join('\n');
+    // Build singleline format (logs)
+    const singlelineParts = ['error', error.code, error.message];
+    if (error.severity)
+        singlelineParts.push(`severity=${error.severity}`);
+    if (error.field)
+        singlelineParts.push(`field=${error.field}`);
+    if (error.hint) {
+        // Escape quotes in hint for proper log formatting
+        const escapedHint = error.hint.replace(/"/g, '\\"');
+        singlelineParts.push(`hint="${escapedHint}"`);
+    }
+    if (error.suggested_action) {
+        const escapedAction = error.suggested_action.replace(/"/g, '\\"');
+        singlelineParts.push(`action="${escapedAction}"`);
+    }
+    if (error.docs)
+        singlelineParts.push(`docs=${error.docs}`);
+    const singleline = singlelineParts.join(' | ');
+    // Build JSON format (APIs)
+    const jsonObj = {
+        code: error.code,
+        message: error.message,
+    };
+    if (error.severity)
+        jsonObj.severity = error.severity;
+    if (error.field)
+        jsonObj.field = error.field;
+    if (error.hint)
+        jsonObj.hint = error.hint;
+    if (error.suggested_action)
+        jsonObj.suggested_action = error.suggested_action;
+    if (error.docs)
+        jsonObj.docs = error.docs;
+    const json = JSON.stringify(jsonObj);
+    // Build markdown format (documentation)
+    const markdownParts = [
+        `**Error:** ${error.message}`,
+        `**Code:** \`${error.code}\``,
+    ];
+    if (error.severity)
+        markdownParts.push(`**Severity:** ${error.severity}`);
+    if (error.field)
+        markdownParts.push(`**Field:** \`${error.field}\``);
+    if (error.hint)
+        markdownParts.push(`**Hint:** ${error.hint}`);
+    if (error.suggested_action)
+        markdownParts.push(`**Action:** ${error.suggested_action}`);
+    if (error.docs)
+        markdownParts.push(`**Docs:** [${error.docs}](${error.docs})`);
+    const markdown = markdownParts.join('\n\n');
+    return {
+        ...error,
+        formats: {
+            multiline,
+            singleline,
+            json,
+            markdown,
+        },
+    };
+}
+/**
+ * Detailed error information for debugging and user-facing messages.
+ * Maps error codes to human-readable descriptions and recovery suggestions.
+ */
+export const ERROR_DETAILS = {
+// Add error details here as needed
+// Example:
+// 'INVALID_CONFIG:TOO_FEW_NODES': {
+//   description: 'Configuration specifies fewer than 2 storage nodes',
+//   recovery: 'Add more storage nodes. At least 2 required, 3+ recommended.'
+// }
+};
+//# sourceMappingURL=errors.js.map

package/dist-standalone/_deps/ux-helpers/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist-standalone/_deps/ux-helpers/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * UX Helpers
+ *
+ * Shared utilities for consistent UX across all PRIVATE.ME packages.
+ *
+ * @packageDocumentation
+ */
+export type { PaginationOptions, PaginatedResult, SearchOptions, ProgressCallback, ACIErrorDetail, ACIErrorOptions, FormattedOutput, FormattedError, } from './types.js';
+export { paginate, createPaginationMetadata } from './pagination.js';
+export { search } from './search.js';
+export { ProgressReporter, createStagedProgress } from './progress.js';
+export { createDetailedError, formatErrorForUser, formatErrorForLog, isACIError, toACIError, formatErrorStructured, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist-standalone/_deps/ux-helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAGrE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAGvE,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist-standalone/_deps/ux-helpers/index.js

@@ -0,0 +1,16 @@
+/**
+ * UX Helpers
+ *
+ * Shared utilities for consistent UX across all PRIVATE.ME packages.
+ *
+ * @packageDocumentation
+ */
+// Re-export pagination utilities
+export { paginate, createPaginationMetadata } from './pagination.js';
+// Re-export search utilities
+export { search } from './search.js';
+// Re-export progress utilities
+export { ProgressReporter, createStagedProgress } from './progress.js';
+// Re-export error utilities
+export { createDetailedError, formatErrorForUser, formatErrorForLog, isACIError, toACIError, formatErrorStructured, } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist-standalone/_deps/ux-helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAcH,iCAAiC;AACjC,OAAO,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAErE,6BAA6B;AAC7B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,+BAA+B;AAC/B,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEvE,4BAA4B;AAC5B,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,qBAAqB,GACtB,MAAM,aAAa,CAAC"}

package/dist-standalone/_deps/ux-helpers/pagination.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Pagination Helper
+ *
+ * Provides consistent pagination behavior across all PRIVATE.ME packages.
+ */
+import type { PaginationOptions, PaginatedResult } from './types.js';
+/**
+ * Paginate a collection of items.
+ *
+ * Returns a subset of items for the requested page along with pagination metadata.
+ *
+ * @param items Full collection to paginate
+ * @param options Pagination options (page number, limit)
+ * @returns Paginated result with data and metadata
+ *
+ * @example
+ * ```typescript
+ * const allItems = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * const result = paginate(allItems, { page: 2, limit: 3 });
+ * // result.data = [4, 5, 6]
+ * // result.pagination.page = 2
+ * // result.pagination.total = 10
+ * // result.pagination.totalPages = 4
+ * // result.pagination.hasNext = true
+ * // result.pagination.hasPrev = true
+ * ```
+ */
+export declare function paginate<T>(items: readonly T[], options?: PaginationOptions): PaginatedResult<T>;
+/**
+ * Create pagination metadata without slicing data.
+ *
+ * Useful when you already have the page data and just need the metadata.
+ *
+ * @param total Total number of items in the full collection
+ * @param options Pagination options
+ * @returns Pagination metadata only
+ */
+export declare function createPaginationMetadata(total: number, options?: PaginationOptions): PaginatedResult<never>['pagination'];
+//# sourceMappingURL=pagination.d.ts.map

package/dist-standalone/_deps/ux-helpers/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAQrE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EACxB,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,eAAe,CAAC,CAAC,CAAC,CAgCpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,eAAe,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAkBtC"}

package/dist-standalone/_deps/ux-helpers/pagination.js

@@ -0,0 +1,79 @@
+/**
+ * Pagination Helper
+ *
+ * Provides consistent pagination behavior across all PRIVATE.ME packages.
+ */
+/** Default items per page. */
+const DEFAULT_LIMIT = 50;
+/** Maximum items per page. */
+const MAX_LIMIT = 100;
+/**
+ * Paginate a collection of items.
+ *
+ * Returns a subset of items for the requested page along with pagination metadata.
+ *
+ * @param items Full collection to paginate
+ * @param options Pagination options (page number, limit)
+ * @returns Paginated result with data and metadata
+ *
+ * @example
+ * ```typescript
+ * const allItems = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+ * const result = paginate(allItems, { page: 2, limit: 3 });
+ * // result.data = [4, 5, 6]
+ * // result.pagination.page = 2
+ * // result.pagination.total = 10
+ * // result.pagination.totalPages = 4
+ * // result.pagination.hasNext = true
+ * // result.pagination.hasPrev = true
+ * ```
+ */
+export function paginate(items, options) {
+    // Normalize pagination parameters
+    const page = Math.max(1, options?.page ?? 1);
+    const limit = Math.min(Math.max(1, options?.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+    const total = items.length;
+    const totalPages = Math.max(1, Math.ceil(total / limit));
+    // Clamp page to valid range
+    const safePage = Math.min(page, totalPages);
+    // Calculate slice indices
+    const startIndex = (safePage - 1) * limit;
+    const endIndex = Math.min(startIndex + limit, total);
+    // Extract page data
+    const data = items.slice(startIndex, endIndex);
+    return {
+        data,
+        pagination: {
+            page: safePage,
+            limit,
+            total,
+            totalPages,
+            hasNext: safePage < totalPages,
+            hasPrev: safePage > 1,
+        },
+    };
+}
+/**
+ * Create pagination metadata without slicing data.
+ *
+ * Useful when you already have the page data and just need the metadata.
+ *
+ * @param total Total number of items in the full collection
+ * @param options Pagination options
+ * @returns Pagination metadata only
+ */
+export function createPaginationMetadata(total, options) {
+    const page = Math.max(1, options?.page ?? 1);
+    const limit = Math.min(Math.max(1, options?.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
+    const totalPages = Math.max(1, Math.ceil(total / limit));
+    const safePage = Math.min(page, totalPages);
+    return {
+        page: safePage,
+        limit,
+        total,
+        totalPages,
+        hasNext: safePage < totalPages,
+        hasPrev: safePage > 1,
+    };
+}
+//# sourceMappingURL=pagination.js.map

package/dist-standalone/_deps/ux-helpers/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,8BAA8B;AAC9B,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,8BAA8B;AAC9B,MAAM,SAAS,GAAG,GAAG,CAAC;AAEtB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAmB,EACnB,OAA2B;IAE3B,kCAAkC;IAClC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,aAAa,CAAC,EAC5C,SAAS,CACV,CAAC;IAEF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;IAC3B,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IAEzD,4BAA4B;IAC5B,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAE5C,0BAA0B;IAC1B,MAAM,UAAU,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,GAAG,KAAK,EAAE,KAAK,CAAC,CAAC;IAErD,oBAAoB;IACpB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAE/C,OAAO;QACL,IAAI;QACJ,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,KAAK;YACL,KAAK;YACL,UAAU;YACV,OAAO,EAAE,QAAQ,GAAG,UAAU;YAC9B,OAAO,EAAE,QAAQ,GAAG,CAAC;SACtB;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAa,EACb,OAA2B;IAE3B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,aAAa,CAAC,EAC5C,SAAS,CACV,CAAC;IAEF,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;IACzD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAE5C,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK;QACL,KAAK;QACL,UAAU;QACV,OAAO,EAAE,QAAQ,GAAG,UAAU;QAC9B,OAAO,EAAE,QAAQ,GAAG,CAAC;KACtB,CAAC;AACJ,CAAC"}

package/dist-standalone/_deps/ux-helpers/progress.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Progress Reporter
+ *
+ * Provides consistent progress reporting for long-running operations.
+ */
+import type { ProgressCallback } from './types.js';
+/**
+ * Progress reporter for long-running operations.
+ *
+ * Wraps a progress callback with convenient methods for reporting status updates.
+ *
+ * @example
+ * ```typescript
+ * async function processLargeFile(
+ *   data: Uint8Array,
+ *   onProgress?: ProgressCallback
+ * ): Promise<void> {
+ *   const progress = new ProgressReporter(onProgress);
+ *
+ *   progress.start('Initializing...');
+ *   // ... initialization work
+ *
+ *   progress.update('Processing...', 50);
+ *   // ... processing work
+ *
+ *   progress.complete();
+ * }
+ * ```
+ */
+export declare class ProgressReporter {
+    private readonly callback;
+    private lastPercent;
+    /**
+     * Create a new progress reporter.
+     *
+     * @param callback Optional callback to invoke on progress updates
+     */
+    constructor(callback?: ProgressCallback);
+    /**
+     * Report progress with status and optional percentage.
+     *
+     * @param status Human-readable status message
+     * @param percent Progress percentage (0-100), optional
+     */
+    report(status: string, percent?: number): void;
+    /**
+     * Report the start of an operation (0% progress).
+     *
+     * @param status Status message
+     */
+    start(status: string): void;
+    /**
+     * Update progress with status and percentage.
+     *
+     * @param status Status message
+     * @param percent Progress percentage (0-100)
+     */
+    update(status: string, percent: number): void;
+    /**
+     * Report completion (100% progress).
+     */
+    complete(): void;
+    /**
+     * Get the last reported percentage.
+     *
+     * @returns Last reported percentage (0-100)
+     */
+    getLastPercent(): number;
+}
+/**
+ * Create a progress reporter that tracks multiple stages.
+ *
+ * Divides the 0-100% range into equal segments for each stage.
+ *
+ * @param stages Array of stage names
+ * @param callback Progress callback
+ * @returns Object with methods for advancing through stages
+ *
+ * @example
+ * ```typescript
+ * const progress = createStagedProgress(
+ *   ['Initializing', 'Processing', 'Finalizing'],
+ *   (status, percent) => console.log(`${status}: ${percent}%`)
+ * );
+ *
+ * progress.start(); // "Initializing: 0%"
+ * progress.nextStage(); // "Processing: 33%"
+ * progress.nextStage(); // "Finalizing: 67%"
+ * progress.complete(); // "Complete: 100%"
+ * ```
+ */
+export declare function createStagedProgress(stages: readonly string[], callback?: ProgressCallback): {
+    start: () => void;
+    nextStage: () => void;
+    complete: () => void;
+    getCurrentStage: () => string;
+    getProgress: () => number;
+};
+//# sourceMappingURL=progress.d.ts.map

package/dist-standalone/_deps/ux-helpers/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,WAAW,CAAa;IAEhC;;;;OAIG;gBACS,QAAQ,CAAC,EAAE,gBAAgB;IAIvC;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAgB9C;;;;OAIG;IACH,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAI3B;;;;;OAKG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAI7C;;OAEG;IACH,QAAQ,IAAI,IAAI;IAIhB;;;;OAIG;IACH,cAAc,IAAI,MAAM;CAGzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,QAAQ,CAAC,EAAE,gBAAgB,GAC1B;IACD,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,IAAI,CAAC;IACrB,eAAe,EAAE,MAAM,MAAM,CAAC;IAC9B,WAAW,EAAE,MAAM,MAAM,CAAC;CAC3B,CA+BA"}

package/dist-standalone/_deps/ux-helpers/progress.js

@@ -0,0 +1,138 @@
+/**
+ * Progress Reporter
+ *
+ * Provides consistent progress reporting for long-running operations.
+ */
+/**
+ * Progress reporter for long-running operations.
+ *
+ * Wraps a progress callback with convenient methods for reporting status updates.
+ *
+ * @example
+ * ```typescript
+ * async function processLargeFile(
+ *   data: Uint8Array,
+ *   onProgress?: ProgressCallback
+ * ): Promise<void> {
+ *   const progress = new ProgressReporter(onProgress);
+ *
+ *   progress.start('Initializing...');
+ *   // ... initialization work
+ *
+ *   progress.update('Processing...', 50);
+ *   // ... processing work
+ *
+ *   progress.complete();
+ * }
+ * ```
+ */
+export class ProgressReporter {
+    callback;
+    lastPercent = 0;
+    /**
+     * Create a new progress reporter.
+     *
+     * @param callback Optional callback to invoke on progress updates
+     */
+    constructor(callback) {
+        this.callback = callback;
+    }
+    /**
+     * Report progress with status and optional percentage.
+     *
+     * @param status Human-readable status message
+     * @param percent Progress percentage (0-100), optional
+     */
+    report(status, percent) {
+        // Clamp percent to valid range if provided
+        const normalizedPercent = percent !== undefined ? Math.max(0, Math.min(100, percent)) : undefined;
+        // Update last known percent
+        if (normalizedPercent !== undefined) {
+            this.lastPercent = normalizedPercent;
+        }
+        // Call callback if provided
+        if (this.callback) {
+            this.callback(status, normalizedPercent);
+        }
+    }
+    /**
+     * Report the start of an operation (0% progress).
+     *
+     * @param status Status message
+     */
+    start(status) {
+        this.report(status, 0);
+    }
+    /**
+     * Update progress with status and percentage.
+     *
+     * @param status Status message
+     * @param percent Progress percentage (0-100)
+     */
+    update(status, percent) {
+        this.report(status, percent);
+    }
+    /**
+     * Report completion (100% progress).
+     */
+    complete() {
+        this.report('Complete', 100);
+    }
+    /**
+     * Get the last reported percentage.
+     *
+     * @returns Last reported percentage (0-100)
+     */
+    getLastPercent() {
+        return this.lastPercent;
+    }
+}
+/**
+ * Create a progress reporter that tracks multiple stages.
+ *
+ * Divides the 0-100% range into equal segments for each stage.
+ *
+ * @param stages Array of stage names
+ * @param callback Progress callback
+ * @returns Object with methods for advancing through stages
+ *
+ * @example
+ * ```typescript
+ * const progress = createStagedProgress(
+ *   ['Initializing', 'Processing', 'Finalizing'],
+ *   (status, percent) => console.log(`${status}: ${percent}%`)
+ * );
+ *
+ * progress.start(); // "Initializing: 0%"
+ * progress.nextStage(); // "Processing: 33%"
+ * progress.nextStage(); // "Finalizing: 67%"
+ * progress.complete(); // "Complete: 100%"
+ * ```
+ */
+export function createStagedProgress(stages, callback) {
+    const reporter = new ProgressReporter(callback);
+    let currentStageIndex = 0;
+    const percentPerStage = stages.length > 0 ? 100 / stages.length : 100;
+    return {
+        start: () => {
+            currentStageIndex = 0;
+            reporter.start(stages[0] ?? 'Starting...');
+        },
+        nextStage: () => {
+            currentStageIndex = Math.min(currentStageIndex + 1, stages.length - 1);
+            const percent = Math.round(currentStageIndex * percentPerStage);
+            reporter.update(stages[currentStageIndex] ?? 'Processing...', percent);
+        },
+        complete: () => {
+            currentStageIndex = stages.length;
+            reporter.complete();
+        },
+        getCurrentStage: () => {
+            return stages[currentStageIndex] ?? '';
+        },
+        getProgress: () => {
+            return Math.round(currentStageIndex * percentPerStage);
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist-standalone/_deps/ux-helpers/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,gBAAgB;IACV,QAAQ,CAA+B;IAChD,WAAW,GAAW,CAAC,CAAC;IAEhC;;;;OAIG;IACH,YAAY,QAA2B;QACrC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc,EAAE,OAAgB;QACrC,2CAA2C;QAC3C,MAAM,iBAAiB,GACrB,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE1E,4BAA4B;QAC5B,IAAI,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACpC,IAAI,CAAC,WAAW,GAAG,iBAAiB,CAAC;QACvC,CAAC;QAED,4BAA4B;QAC5B,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,MAAc;QAClB,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACzB,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,MAAc,EAAE,OAAe;QACpC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,QAAQ;QACN,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAyB,EACzB,QAA2B;IAQ3B,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAE1B,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;IAEtE,OAAO;QACL,KAAK,EAAE,GAAG,EAAE;YACV,iBAAiB,GAAG,CAAC,CAAC;YACtB,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC;QAC7C,CAAC;QAED,SAAS,EAAE,GAAG,EAAE;YACd,iBAAiB,GAAG,IAAI,CAAC,GAAG,CAAC,iBAAiB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACvE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,iBAAiB,GAAG,eAAe,CAAC,CAAC;YAChE,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,eAAe,EAAE,OAAO,CAAC,CAAC;QACzE,CAAC;QAED,QAAQ,EAAE,GAAG,EAAE;YACb,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC;YAClC,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACtB,CAAC;QAED,eAAe,EAAE,GAAG,EAAE;YACpB,OAAO,MAAM,CAAC,iBAAiB,CAAC,IAAI,EAAE,CAAC;QACzC,CAAC;QAED,WAAW,EAAE,GAAG,EAAE;YAChB,OAAO,IAAI,CAAC,KAAK,CAAC,iBAAiB,GAAG,eAAe,CAAC,CAAC;QACzD,CAAC;KACF,CAAC;AACJ,CAAC"}