@fgv/ts-res-ui-components 5.0.0-21 → 5.0.0-23

package/lib/utils/observability/implementations.js

@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import { Logging, succeed } from '@fgv/ts-utils';
+/**
+ * Console-based user logger that extends diagnostic logging with success method.
+ * @public
+ */
+export class ConsoleUserLogger extends Logging.LoggerBase {
+    /**
+     * Creates a new console user logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel) {
+        super(logLevel);
+    }
+    /**
+     * {@inheritDoc ObservabilityTools.IUserLogger.success}
+     */
+    success(message, ...parameters) {
+        return this.log('info', message, ...parameters);
+    }
+    /**
+     * implements base class _log.
+     */
+    _log(message, level) {
+        switch (level) {
+            case 'error':
+                console.error(message);
+                break;
+            case 'warning':
+                console.warn(message);
+                break;
+            case 'info':
+                console.info(message);
+                break;
+            default:
+                console.log(message);
+                break;
+        }
+        return succeed(message);
+    }
+}
+/**
+ * No-op user logger that suppresses all output.
+ * @public
+ */
+export class NoOpUserLogger extends Logging.LoggerBase {
+    /**
+     * Creates a new no-op user logger.
+     * @param logLevel - The level of logging to be used.
+     */
+    constructor(logLevel) {
+        super(logLevel);
+    }
+    /**
+     * {@inheritDoc ObservabilityTools.IUserLogger.success}
+     */
+    success(message, ...parameters) {
+        return succeed(undefined);
+    }
+    /**
+     * Implements base class _log method.
+     */
+    _log(message, __level) {
+        // no-op
+        return succeed(message);
+    }
+}
+/**
+ * Observability context that provides both diagnostic and user logging capabilities.
+ * @public
+ */
+export class ObservabilityContext {
+    /**
+     * Creates a new observability context.
+     * @param diag - The diagnostic logger.
+     * @param user - The user logger.
+     */
+    constructor(diag, user) {
+        this.diag = diag;
+        this.user = user;
+    }
+}
+//# sourceMappingURL=implementations.js.map

package/lib/utils/observability/index.d.ts

@@ -0,0 +1,4 @@
+export type { IUserLogger, IObservabilityContext } from './interfaces';
+export { ConsoleUserLogger, NoOpUserLogger, ObservabilityContext } from './implementations';
+export { createConsoleObservabilityContext, createNoOpObservabilityContext, DefaultObservabilityContext, TestObservabilityContext } from './factories';
+//# sourceMappingURL=index.d.ts.map

package/lib/utils/observability/index.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+// Export implementations
+export { ConsoleUserLogger, NoOpUserLogger, ObservabilityContext } from './implementations';
+// Export factories
+export { createConsoleObservabilityContext, createNoOpObservabilityContext, DefaultObservabilityContext, TestObservabilityContext } from './factories';
+//# sourceMappingURL=index.js.map

package/lib/utils/observability/interfaces.d.ts

@@ -0,0 +1,30 @@
+import type { Logging, Success } from '@fgv/ts-utils';
+/**
+ * User logger interface that extends ILogger with success method for UI feedback.
+ * @public
+ */
+export interface IUserLogger extends Logging.ILogger {
+    /**
+     * Logs a success message for user feedback.
+     * @param message - The message to log.
+     * @param parameters - The parameters to log.
+     * @returns `Success` with the logged message if the level is enabled, or
+     * `Success` with `undefined` if the message is suppressed.
+     */
+    success(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+}
+/**
+ * Observability context that provides both diagnostic and user logging capabilities.
+ * @public
+ */
+export interface IObservabilityContext {
+    /**
+     * Diagnostic logger for internal system diagnostics.
+     */
+    readonly diag: Logging.ILogger;
+    /**
+     * User logger for user-facing messages and feedback.
+     */
+    readonly user: IUserLogger;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/lib/utils/observability/interfaces.js

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2025 Erik Fortune
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+export {};
+//# sourceMappingURL=interfaces.js.map

package/lib/utils/resolutionEditing.js

@@ -1,6 +1,7 @@
 import { succeed, fail } from '@fgv/ts-utils';
 import { Runtime } from '@fgv/ts-res';
 import { Diff } from '@fgv/ts-json';
+import { isJsonObject } from '@fgv/ts-json-base';
 /**
  * Validates an edited resource JSON value
  */
@@ -67,7 +68,7 @@ export function computeResourceDelta(baseValue, resolvedValue, editedValue) {
  * Recursively adds null values to delta for all properties in the deleted object
  */
 function addDeletionsAsNull(deleted, delta) {
-    if (typeof deleted === 'object' && deleted !== null && !Array.isArray(deleted)) {
+    if (isJsonObject(deleted)) {
         const deletedObj = deleted;
         for (const key in deletedObj) {
             if (deletedObj.hasOwnProperty(key)) {

package/lib/utils/resourceSelector.d.ts

@@ -0,0 +1,97 @@
+import { Result } from '@fgv/ts-utils';
+import { ProcessedResources, GridResourceSelector } from '../types';
+/**
+ * Handler function type for resource selector implementations.
+ */
+type SelectorHandler = (selector: any, resources: ProcessedResources) => Result<string[]>;
+/**
+ * Resource selector utility for filtering resources based on various criteria.
+ * Supports built-in selector types and extensible custom selectors.
+ *
+ * @example
+ * ```typescript
+ * const selector = new ResourceSelector();
+ *
+ * // Use built-in selectors
+ * const prefixResult = selector.select(
+ *   { type: 'prefix', prefix: 'user.' },
+ *   processedResources
+ * );
+ *
+ * // Register and use custom selector
+ * selector.registerSelector('byMetadata', (config, resources) => {
+ *   return succeed(resources.summary.resourceIds.filter(id =>
+ *     hasMetadata(id, config.key, config.value)
+ *   ));
+ * });
+ * ```
+ * @public
+ */
+export declare class ResourceSelector {
+    private registry;
+    constructor();
+    /**
+     * Register a new selector type that can be used in grid configurations.
+     *
+     * @param type - Unique identifier for the selector type
+     * @param handler - Function that implements the selection logic
+     */
+    registerSelector(type: string, handler: SelectorHandler): void;
+    /**
+     * Get all registered selector types (useful for debugging/tooling).
+     */
+    getRegisteredTypes(): string[];
+    /**
+     * Select resources based on the provided selector configuration.
+     *
+     * @param selector - Resource selector configuration
+     * @param resources - Processed resources to select from
+     * @returns Result containing array of selected resource IDs
+     */
+    select(selector: GridResourceSelector, resources: ProcessedResources): Result<string[]>;
+    /**
+     * Select resources by explicit resource IDs.
+     */
+    private selectByIds;
+    /**
+     * Select resources with IDs starting with the specified prefix.
+     */
+    private selectByPrefix;
+    /**
+     * Select resources with IDs ending with the specified suffix.
+     */
+    private selectBySuffix;
+    /**
+     * Select resources by resource type names.
+     */
+    private selectByResourceTypes;
+    /**
+     * Select resources by simple glob pattern matching.
+     * Supports * as wildcard character.
+     */
+    private selectByPattern;
+    /**
+     * Select all available resources.
+     */
+    private selectAll;
+    /**
+     * Select resources using custom selector logic.
+     */
+    private selectCustom;
+}
+/**
+ * Default resource selector instance for use throughout the application.
+ * @public
+ */
+export declare const defaultResourceSelector: ResourceSelector;
+/**
+ * Utility function to select resources using the default selector.
+ *
+ * @param selector - Resource selector configuration
+ * @param resources - Processed resources to select from
+ * @returns Result containing array of selected resource IDs
+ * @public
+ */
+export declare function selectResources(selector: GridResourceSelector, resources: ProcessedResources): Result<string[]>;
+export {};
+//# sourceMappingURL=resourceSelector.d.ts.map

package/lib/utils/resourceSelector.js

@@ -0,0 +1,195 @@
+import { succeed, fail } from '@fgv/ts-utils';
+/**
+ * Resource selector utility for filtering resources based on various criteria.
+ * Supports built-in selector types and extensible custom selectors.
+ *
+ * @example
+ * ```typescript
+ * const selector = new ResourceSelector();
+ *
+ * // Use built-in selectors
+ * const prefixResult = selector.select(
+ *   { type: 'prefix', prefix: 'user.' },
+ *   processedResources
+ * );
+ *
+ * // Register and use custom selector
+ * selector.registerSelector('byMetadata', (config, resources) => {
+ *   return succeed(resources.summary.resourceIds.filter(id =>
+ *     hasMetadata(id, config.key, config.value)
+ *   ));
+ * });
+ * ```
+ * @public
+ */
+export class ResourceSelector {
+    constructor() {
+        this.registry = new Map();
+        /**
+         * Select resources by explicit resource IDs.
+         */
+        this.selectByIds = (selector, resources) => {
+            const availableIds = new Set(resources.summary.resourceIds);
+            const selectedIds = selector.resourceIds.filter((id) => availableIds.has(id));
+            if (selectedIds.length === 0 && selector.resourceIds.length > 0) {
+                return fail(`None of the specified resource IDs were found in the resource collection`);
+            }
+            return succeed(selectedIds);
+        };
+        /**
+         * Select resources with IDs starting with the specified prefix.
+         */
+        this.selectByPrefix = (selector, resources) => {
+            if (!selector.prefix) {
+                return fail('Prefix cannot be empty');
+            }
+            const matchingIds = resources.summary.resourceIds.filter((id) => id.startsWith(selector.prefix));
+            return succeed(matchingIds);
+        };
+        /**
+         * Select resources with IDs ending with the specified suffix.
+         */
+        this.selectBySuffix = (selector, resources) => {
+            if (!selector.suffix) {
+                return fail('Suffix cannot be empty');
+            }
+            const matchingIds = resources.summary.resourceIds.filter((id) => id.endsWith(selector.suffix));
+            return succeed(matchingIds);
+        };
+        /**
+         * Select resources by resource type names.
+         */
+        this.selectByResourceTypes = (selector, resources) => {
+            if (!selector.types || selector.types.length === 0) {
+                return fail('Resource types array cannot be empty');
+            }
+            const typeSet = new Set(selector.types);
+            const matchingIds = [];
+            // Iterate through all resources and check their types
+            resources.summary.resourceIds.forEach((resourceId) => {
+                try {
+                    // Get the resource from the resolver to check its type
+                    const resourceResult = resources.resolver.resourceManager.getBuiltResource(resourceId);
+                    if (resourceResult.isSuccess()) {
+                        const resource = resourceResult.value;
+                        if (typeSet.has(resource.resourceType.key)) {
+                            matchingIds.push(resourceId);
+                        }
+                    }
+                }
+                catch {
+                    // Skip resources that can't be accessed
+                }
+            });
+            return succeed(matchingIds);
+        };
+        /**
+         * Select resources by simple glob pattern matching.
+         * Supports * as wildcard character.
+         */
+        this.selectByPattern = (selector, resources) => {
+            if (!selector.pattern) {
+                return fail('Pattern cannot be empty');
+            }
+            try {
+                // Convert glob pattern to regex
+                const regexPattern = selector.pattern
+                    .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape special regex chars
+                    .replace(/\*/g, '.*'); // Convert * to .*
+                const regex = new RegExp(`^${regexPattern}$`);
+                const matchingIds = resources.summary.resourceIds.filter((id) => regex.test(id));
+                return succeed(matchingIds);
+            }
+            catch (error) {
+                return fail(`Invalid pattern: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        };
+        /**
+         * Select all available resources.
+         */
+        this.selectAll = (_selector, resources) => {
+            return succeed([...resources.summary.resourceIds]);
+        };
+        /**
+         * Select resources using custom selector logic.
+         */
+        this.selectCustom = (selector, resources) => {
+            if (!selector.selector) {
+                return fail('Custom selector configuration is required');
+            }
+            try {
+                const selectedIds = selector.selector.select(resources);
+                // Validate that all returned IDs exist in the resource collection
+                const availableIds = new Set(resources.summary.resourceIds);
+                const validIds = selectedIds.filter((id) => availableIds.has(id));
+                if (validIds.length !== selectedIds.length) {
+                    const invalidIds = selectedIds.filter((id) => !availableIds.has(id));
+                    console.warn(`Custom selector returned invalid resource IDs: ${invalidIds.join(', ')}`);
+                }
+                return succeed(validIds);
+            }
+            catch (error) {
+                return fail(`Custom selector failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        };
+        // Register built-in selectors
+        this.registry.set('ids', this.selectByIds);
+        this.registry.set('prefix', this.selectByPrefix);
+        this.registry.set('suffix', this.selectBySuffix);
+        this.registry.set('resourceTypes', this.selectByResourceTypes);
+        this.registry.set('pattern', this.selectByPattern);
+        this.registry.set('all', this.selectAll);
+        this.registry.set('custom', this.selectCustom);
+    }
+    /**
+     * Register a new selector type that can be used in grid configurations.
+     *
+     * @param type - Unique identifier for the selector type
+     * @param handler - Function that implements the selection logic
+     */
+    registerSelector(type, handler) {
+        this.registry.set(type, handler);
+    }
+    /**
+     * Get all registered selector types (useful for debugging/tooling).
+     */
+    getRegisteredTypes() {
+        return Array.from(this.registry.keys());
+    }
+    /**
+     * Select resources based on the provided selector configuration.
+     *
+     * @param selector - Resource selector configuration
+     * @param resources - Processed resources to select from
+     * @returns Result containing array of selected resource IDs
+     */
+    select(selector, resources) {
+        const handler = this.registry.get(selector.type);
+        if (!handler) {
+            return fail(`Unknown selector type: ${selector.type}`);
+        }
+        try {
+            return handler(selector, resources);
+        }
+        catch (error) {
+            return fail(`Selector error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+/**
+ * Default resource selector instance for use throughout the application.
+ * @public
+ */
+export const defaultResourceSelector = new ResourceSelector();
+/**
+ * Utility function to select resources using the default selector.
+ *
+ * @param selector - Resource selector configuration
+ * @param resources - Processed resources to select from
+ * @returns Result containing array of selected resource IDs
+ * @public
+ */
+export function selectResources(selector, resources) {
+    return defaultResourceSelector.select(selector, resources);
+}
+//# sourceMappingURL=resourceSelector.js.map

package/lib/utils/resourceSelectors.d.ts

@@ -0,0 +1,146 @@
+import { ResourceJson } from '@fgv/ts-res';
+import { Result } from '@fgv/ts-utils';
+/**
+ * Helper functions for working with pending resources and resource IDs.
+ * These utilities provide standardized ways to work with resource identification
+ * and selection patterns commonly needed by host applications.
+ *
+ * @public
+ */
+/**
+ * Gets pending resources filtered by resource type.
+ *
+ * @param pendingResources - Map of pending resources (keys are guaranteed to be full resource IDs)
+ * @param resourceType - Resource type to filter by (e.g., 'json', 'string')
+ * @returns Array of pending resources of the specified type
+ *
+ * @example
+ * ```typescript
+ * const jsonResources = getPendingAdditionsByType(pendingResources, 'json');
+ * const languageConfigs = getPendingAdditionsByType(pendingResources, 'languageConfig');
+ * ```
+ *
+ * @public
+ */
+export declare function getPendingAdditionsByType(pendingResources: Map<string, ResourceJson.Json.ILooseResourceDecl>, resourceType: string): Array<{
+    id: string;
+    resource: ResourceJson.Json.ILooseResourceDecl;
+}>;
+/**
+ * Checks if a resource ID corresponds to a pending addition.
+ *
+ * @param resourceId - Resource ID to check (should be full resource ID)
+ * @param pendingResources - Map of pending resources
+ * @returns True if the resource ID exists in pending resources
+ *
+ * @example
+ * ```typescript
+ * if (isPendingAddition('platform.languages.az-AZ', pendingResources)) {
+ *   console.log('This is a pending resource');
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function isPendingAddition(resourceId: string, pendingResources: Map<string, ResourceJson.Json.ILooseResourceDecl>): boolean;
+/**
+ * Derives a leaf ID from a full resource ID.
+ * Extracts the last segment after the final dot.
+ *
+ * @param fullResourceId - Full resource ID (e.g., 'platform.languages.az-AZ')
+ * @returns Result containing the leaf ID (e.g., 'az-AZ') or error if invalid format
+ *
+ * @example
+ * ```typescript
+ * const leafResult = deriveLeafId('platform.languages.az-AZ');
+ * if (leafResult.isSuccess()) {
+ *   console.log(leafResult.value); // 'az-AZ'
+ * }
+ *
+ * const invalidResult = deriveLeafId('invalid');
+ * if (invalidResult.isFailure()) {
+ *   console.log(invalidResult.message); // 'Resource ID must contain at least one dot'
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function deriveLeafId(fullResourceId: string): Result<string>;
+/**
+ * Constructs a full resource ID from a root path and leaf ID.
+ *
+ * @param rootPath - Root path (e.g., 'platform.languages')
+ * @param leafId - Leaf identifier (e.g., 'az-AZ')
+ * @returns Result containing the full resource ID or error if invalid inputs
+ *
+ * @example
+ * ```typescript
+ * const fullIdResult = deriveFullId('platform.languages', 'az-AZ');
+ * if (fullIdResult.isSuccess()) {
+ *   console.log(fullIdResult.value); // 'platform.languages.az-AZ'
+ * }
+ *
+ * const invalidResult = deriveFullId('', 'az-AZ');
+ * if (invalidResult.isFailure()) {
+ *   console.log(invalidResult.message); // 'Root path cannot be empty'
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function deriveFullId(rootPath: string, leafId: string): Result<string>;
+/**
+ * Gets all unique resource types from pending resources.
+ *
+ * @param pendingResources - Map of pending resources
+ * @returns Array of unique resource type names
+ *
+ * @example
+ * ```typescript
+ * const types = getPendingResourceTypes(pendingResources);
+ * console.log(types); // ['json', 'string', 'languageConfig']
+ * ```
+ *
+ * @public
+ */
+export declare function getPendingResourceTypes(pendingResources: Map<string, ResourceJson.Json.ILooseResourceDecl>): string[];
+/**
+ * Gets statistics about pending resources.
+ * Provides summary information useful for UI displays.
+ *
+ * @param pendingResources - Map of pending resources
+ * @returns Statistics object with counts and breakdowns
+ *
+ * @example
+ * ```typescript
+ * const stats = getPendingResourceStats(pendingResources);
+ * console.log(`${stats.totalCount} pending resources`);
+ * console.log(`Types: ${Object.keys(stats.byType).join(', ')}`);
+ * ```
+ *
+ * @public
+ */
+export declare function getPendingResourceStats(pendingResources: Map<string, ResourceJson.Json.ILooseResourceDecl>): {
+    totalCount: number;
+    byType: Record<string, number>;
+    resourceIds: string[];
+};
+/**
+ * Validates that all keys in a pending resources map are properly formatted as full resource IDs.
+ * This is a diagnostic function to ensure the pending resource key invariant is maintained.
+ *
+ * @param pendingResources - Map of pending resources to validate
+ * @returns Result indicating whether all keys are valid full resource IDs, or details about any issues found
+ *
+ * @example
+ * ```typescript
+ * const validation = validatePendingResourceKeys(pendingResources);
+ * if (validation.isFailure()) {
+ *   console.error('Pending resource key validation failed:', validation.message);
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare function validatePendingResourceKeys(pendingResources: Map<string, ResourceJson.Json.ILooseResourceDecl>): Result<void>;
+//# sourceMappingURL=resourceSelectors.d.ts.map