@genesislcap/foundation-utils 14.408.0 → 14.409.0

package/README.md

@@ -1,36 +1,12 @@
-# Genesis Foundation Utils
+# @genesislcap/foundation-utils
 
-The `@genesislcap/foundation-utils` package provides a collection of utility services and helpers designed to facilitate common development tasks within Genesis applications. It aims to enhance productivity by offering reusable solutions for patterns and problems encountered across different projects.
+Documentation for this package is published on the Genesis docs site:
 
-## API Documentation
-
-For more detailed information on API and configurations, please refer to the [API documentation](docs/api/index.md) in the `docs/api` directory.
-
-## Features
-
-The library encompasses a broad range of features, including:
-
-- **[Data](src/data/README.md)** - Manages in-memory databases and data storage solutions.
-- **[Decorators](src/decorators/README.md)** - Provides decorators for enhancing class functionalities, such as rendering on change.
-- **[Design System](src/design-system/README.md)** - Holds the design system configurations and utilities.
-- **[Directives](src/directives/README.md)** - Offers Angular-like directives for DOM manipulations, including conditional rendering and synchronization functionalities.
-- **[ENV](src/env/README.md)** - Contains utilities for environment variable management and detection of development environments.
-- **[Error](src/error/README.md)** - Deals with error mapping and handling strategies.
-- **[Formatters](src/formatters/README.md)** - Includes functions for formatting dates and numbers according to locale settings.
-- **[Logger](src/logger/README.md)** - A simple logging utility for debugging and information tracking.
-- **[Mappers](src/mappers/README.md)** - Focuses on data transformation, especially for DTOs (Data Transfer Objects).
-- **[Mixins](src/mixins/README.md)** - Provides mixins for common functionalities like lifecycle hooks and state management.
-- **[Observer](src/observer/README.md)** - Implements the Observer pattern for reactive programming.
-- **[Resource](src/observer/README.md)** - Defines types and interfaces for resource management.
-- **[Serializers](src/serializers/README.md)** - Contains serializers, particularly for JSON data handling.
-- **[State](src/state/README.md)** - Manages reactive state and provides utilities for state observation.
-- **[Styles](src/styles/README.md)** - Includes utilities for styling, dealing with colors, typography, and DOM styles.
-- **[UUID](src/uuid/README.md)** - Utilities for generating and managing UUIDs.
-- **[Window](src/window/README.md)** - Provides abstractions and utilities for window object manipulations.
+**Docs: [Utility methods](https://docs.genesis.global/docs/develop/client-capabilities/utility-methods/)**
 
 ## Installation
 
-To include `@genesislcap/foundation-utils` in your project, add it as a dependency in your `package.json` file and follow your project's routine for dependency installation.
+Add the package to your `package.json` dependencies. After changing dependencies, run `npm run bootstrap` (or your project's equivalent). See [package.json basics](https://learn.genesis.global/secure/web/basics/package-json-basics/) for more information.
 
 ```json
 {

package/dist/custom-elements.json

@@ -352,6 +352,59 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/decorators/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "*",
+          "declaration": {
+            "name": "*",
+            "package": "./renderOnChange"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/decorators/renderOnChange.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "renderOnChange",
+          "parameters": [
+            {
+              "name": "target",
+              "type": {
+                "text": "FASTElement & { render(): void }"
+              },
+              "description": "The target to define the property change handler on."
+            },
+            {
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "description": "The property name."
+            }
+          ],
+          "description": "Defines a property changed handler that calls a render() method on the target as an internal observation enhancement.",
+          "privacy": "public"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "renderOnChange",
+          "declaration": {
+            "name": "renderOnChange",
+            "module": "src/decorators/renderOnChange.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/encoding/index.ts",
@@ -842,47 +895,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/converters/index.ts",
-      "declarations": [],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "*",
-          "declaration": {
-            "name": "*",
-            "package": "./string-array-converter"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "src/converters/string-array-converter.ts",
-      "declarations": [
-        {
-          "kind": "variable",
-          "name": "stringArrayConverter",
-          "type": {
-            "text": "ValueConverter"
-          },
-          "default": "{\n  fromView(v: string): string | string[] | undefined {\n    if (!v?.trim()) return undefined;\n    return v.includes(',') ? v.split(',').map((s) => s.trim()) : v.trim();\n  },\n  toView(v: string | string[] | undefined): string {\n    if (typeof v === 'string') return v;\n    if (Array.isArray(v)) return v.join(',');\n    return '';\n  },\n}",
-          "description": "A @microsoft/fast-element#ValueConverter that converts between comma-separated string attributes\nand `string | string[]` properties.",
-          "privacy": "public"
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "stringArrayConverter",
-          "declaration": {
-            "name": "stringArrayConverter",
-            "module": "src/converters/string-array-converter.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/data/inMemoryDatabase.ts",
@@ -1083,7 +1095,7 @@
     },
     {
       "kind": "javascript-module",
-      "path": "src/decorators/index.ts",
+      "path": "src/converters/index.ts",
       "declarations": [],
       "exports": [
         {
@@ -1091,45 +1103,33 @@
           "name": "*",
           "declaration": {
             "name": "*",
-            "package": "./renderOnChange"
+            "package": "./string-array-converter"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "src/decorators/renderOnChange.ts",
+      "path": "src/converters/string-array-converter.ts",
       "declarations": [
         {
-          "kind": "function",
-          "name": "renderOnChange",
-          "parameters": [
-            {
-              "name": "target",
-              "type": {
-                "text": "FASTElement & { render(): void }"
-              },
-              "description": "The target to define the property change handler on."
-            },
-            {
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "description": "The property name."
-            }
-          ],
-          "description": "Defines a property changed handler that calls a render() method on the target as an internal observation enhancement.",
+          "kind": "variable",
+          "name": "stringArrayConverter",
+          "type": {
+            "text": "ValueConverter"
+          },
+          "default": "{\n  fromView(v: string): string | string[] | undefined {\n    if (!v?.trim()) return undefined;\n    return v.includes(',') ? v.split(',').map((s) => s.trim()) : v.trim();\n  },\n  toView(v: string | string[] | undefined): string {\n    if (typeof v === 'string') return v;\n    if (Array.isArray(v)) return v.join(',');\n    return '';\n  },\n}",
+          "description": "A @microsoft/fast-element#ValueConverter that converts between comma-separated string attributes\nand `string | string[]` properties.",
           "privacy": "public"
         }
       ],
       "exports": [
         {
           "kind": "js",
-          "name": "renderOnChange",
+          "name": "stringArrayConverter",
           "declaration": {
-            "name": "renderOnChange",
-            "module": "src/decorators/renderOnChange.ts"
+            "name": "stringArrayConverter",
+            "module": "src/converters/string-array-converter.ts"
           }
         }
       ]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/foundation-utils",
   "description": "Genesis Foundation Utils",
-  "version": "14.408.0",
+  "version": "14.409.0",
   "sideEffects": false,
   "license": "SEE LICENSE IN license.txt",
   "main": "dist/esm/index.js",
@@ -29,18 +29,18 @@
     }
   },
   "devDependencies": {
-    "@genesislcap/foundation-testing": "14.408.0",
-    "@genesislcap/genx": "14.408.0",
-    "@genesislcap/rollup-builder": "14.408.0",
-    "@genesislcap/ts-builder": "14.408.0",
-    "@genesislcap/uvu-playwright-builder": "14.408.0",
-    "@genesislcap/vite-builder": "14.408.0",
-    "@genesislcap/webpack-builder": "14.408.0",
+    "@genesislcap/foundation-testing": "14.409.0",
+    "@genesislcap/genx": "14.409.0",
+    "@genesislcap/rollup-builder": "14.409.0",
+    "@genesislcap/ts-builder": "14.409.0",
+    "@genesislcap/uvu-playwright-builder": "14.409.0",
+    "@genesislcap/vite-builder": "14.409.0",
+    "@genesislcap/webpack-builder": "14.409.0",
     "@types/json-schema": "^7.0.11"
   },
   "dependencies": {
-    "@genesislcap/expression-builder": "14.408.0",
-    "@genesislcap/foundation-logger": "14.408.0",
+    "@genesislcap/expression-builder": "14.409.0",
+    "@genesislcap/foundation-logger": "14.409.0",
     "@microsoft/fast-components": "2.30.6",
     "@microsoft/fast-element": "1.14.0",
     "@microsoft/fast-foundation": "2.50.0",
@@ -58,5 +58,5 @@
     "access": "public"
   },
   "customElements": "dist/custom-elements.json",
-  "gitHead": "26b08831fd001b4ee95c8a0d3364a18c0ec4005b"
+  "gitHead": "cbe0459d170f27c35a7de18cec415947aedf4da5"
 }

package/docs/api/foundation-utils.accept_terms_url.md

@@ -1,12 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [ACCEPT\_TERMS\_URL](./foundation-utils.accept_terms_url.md)
-
-## ACCEPT\_TERMS\_URL variable
-
-
-**Signature:**
-
-```typescript
-ACCEPT_TERMS_URL: string
-```

package/docs/api/foundation-utils.activecolorscheme.md

@@ -1,13 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [activeColorScheme](./foundation-utils.activecolorscheme.md)
-
-## activeColorScheme variable
-
-A design token that represents the active color scheme (light or dark).
-
-**Signature:**
-
-```typescript
-activeColorScheme: import("@microsoft/fast-foundation").CSSDesignToken<string>
-```

package/docs/api/foundation-utils.api_host.md

@@ -1,22 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [API\_HOST](./foundation-utils.api_host.md)
-
-## API\_HOST variable
-
-The Genesis Server URL (WebSocket or HTTP).
-
-**Signature:**
-
-```typescript
-_API_HOST: string
-```
-
-## Remarks
-
-Optional.
-
-## Example
-
-ws://localhost/gwf/, ws://localhost:9064
-

package/docs/api/foundation-utils.assuredesignsystem.md

@@ -1,90 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [assureDesignSystem](./foundation-utils.assuredesignsystem.md)
-
-## assureDesignSystem() function
-
-assureDesignSystem.
-
-**Signature:**
-
-```typescript
-export declare function assureDesignSystem(module: DesignSystemModule): DesignSystemModule;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-
-</th><th>
-
-Type
-
-
-</th><th>
-
-Description
-
-
-</th></tr></thead>
-<tbody><tr><td>
-
-module
-
-
-</td><td>
-
-[DesignSystemModule](./foundation-utils.designsystemmodule.md)
-
-
-</td><td>
-
-
-</td></tr>
-</tbody></table>
-
-**Returns:**
-
-[DesignSystemModule](./foundation-utils.designsystemmodule.md)
-
-## Remarks
-
-Webpack caching strategies can backfill missing modules with placeholders in an attempt to prevent errors. In the case of offline remotes, we rely on the error to fall back to local versions. This utility assures we have a design system.
-
-## Example 1
-
-
-```ts
-async function zeroDesignSystemImport(): Promise<DesignSystemModule> {
-  let module: DesignSystemModule;
-  let type: ResourceType = ResourceType.remote;
-  try {
-    module = await import('foundationZero/ZeroDesignSystem');
-    return assureDesignSystem(module);
-  } catch (e) {
-    logger.info(
-      `Please note remoteEntry.js load errors are expected if module federated dependencies are offline. Falling back to locally bundled versions.`,
-    );
-    type = ResourceType.local;
-    module = await import('@genesislcap/foundation-zero');
-    return assureDesignSystem(module);
-  } finally {
-    logger.debug(`Using '${type}' version of foundation-zero`);
-  }
-}
-```
-
-## Example 2
-
-You should also instruct webpack to use strict module handling.
-
-```ts
-output: {
-  strictModuleErrorHandling: true,
-  strictModuleExceptionHandling: true,
-}
-```
-

package/docs/api/foundation-utils.avoidtreeshaking.md

@@ -1,56 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [avoidTreeShaking](./foundation-utils.avoidtreeshaking.md)
-
-## avoidTreeShaking() function
-
-Explicitly prevents tree-shaking of custom element classes by referencing them.
-
-Bundlers may incorrectly remove code that it thinks has no side effects, such as custom element definitions that are only referenced in templates. By passing these classes to `avoidTreeShaking`<!-- -->, we create a side effect that signals to the bundler to preserve the code.
-
-**Signature:**
-
-```typescript
-avoidTreeShaking: (...classes: unknown[]) => void
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-
-</th><th>
-
-Type
-
-
-</th><th>
-
-Description
-
-
-</th></tr></thead>
-<tbody><tr><td>
-
-classes
-
-
-</td><td>
-
-unknown\[\]
-
-
-</td><td>
-
-One or more custom element classes that should not be tree-shaken.
-
-
-</td></tr>
-</tbody></table>
-
-**Returns:**
-
-void
-

package/docs/api/foundation-utils.builder.md

@@ -1,18 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [BUILDER](./foundation-utils.builder.md)
-
-## BUILDER variable
-
-The builder aka file bundler.
-
-**Signature:**
-
-```typescript
-_BUILDER: string
-```
-
-## Example
-
-'webpack', 'vite'.
-

package/docs/api/foundation-utils.change_password_url.md

@@ -1,12 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [CHANGE\_PASSWORD\_URL](./foundation-utils.change_password_url.md)
-
-## CHANGE\_PASSWORD\_URL variable
-
-
-**Signature:**
-
-```typescript
-CHANGE_PASSWORD_URL: string
-```

package/docs/api/foundation-utils.constructablelifecyclehandler.md

@@ -1,12 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [ConstructableLifecycleHandler](./foundation-utils.constructablelifecyclehandler.md)
-
-## ConstructableLifecycleHandler type
-
-
-**Signature:**
-
-```typescript
-export type ConstructableLifecycleHandler = Constructable<FASTElement & HTMLElement>;
-```

package/docs/api/foundation-utils.constructablependingstate.md

@@ -1,13 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [ConstructablePendingState](./foundation-utils.constructablependingstate.md)
-
-## ConstructablePendingState type
-
-A mixin that provides functionality for raising `pending-state` events.
-
-**Signature:**
-
-```typescript
-export declare type ConstructablePendingState = Constructable<FASTElement & HTMLElement>;
-```

package/docs/api/foundation-utils.conversiontype.md

@@ -1,13 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [ConversionType](./foundation-utils.conversiontype.md)
-
-## ConversionType type
-
-Represents the possible types of value conversion for data synchronization.
-
-**Signature:**
-
-```typescript
-export type ConversionType = 'string' | 'number' | 'time' | 'boolean';
-```

package/docs/api/foundation-utils.createerrormap.md

@@ -1,56 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [createErrorMap](./foundation-utils.createerrormap.md)
-
-## createErrorMap() function
-
-A factory to create the error map.
-
-**Signature:**
-
-```typescript
-createErrorMap: <TErrorDetailMap extends ErrorDetailMap>(logger: ErrorMapLogger) => ErrorMap<TErrorDetailMap>
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-
-</th><th>
-
-Type
-
-
-</th><th>
-
-Description
-
-
-</th></tr></thead>
-<tbody><tr><td>
-
-logger
-
-
-</td><td>
-
-[ErrorMapLogger](./foundation-utils.errormaplogger.md)
-
-
-</td><td>
-
-A logger error method reference.
-
-
-</td></tr>
-</tbody></table>
-
-**Returns:**
-
-[ErrorMap](./foundation-utils.errormap.md)<!-- -->&lt;TErrorDetailMap&gt;
-
-A ErrorMap instance.
-

package/docs/api/foundation-utils.createlogger.md

@@ -1,77 +0,0 @@
-<!-- Do not edit this file. It is automatically generated by API Documenter. -->
-
-[Home](./index.md) &gt; [@genesislcap/foundation-utils](./foundation-utils.md) &gt; [createLogger](./foundation-utils.createlogger.md)
-
-## createLogger() function
-
-> Warning: This API is now obsolete.
-> 
-> - Use `createLogger` from `@genesislcap/foundation-logger` instead.
-> 
-
-Creates a logger with the given name and options.
-
-**Signature:**
-
-```typescript
-export declare function createLogger(name: string, options?: LoggerOptions): Logger;
-```
-
-## Parameters
-
-<table><thead><tr><th>
-
-Parameter
-
-
-</th><th>
-
-Type
-
-
-</th><th>
-
-Description
-
-
-</th></tr></thead>
-<tbody><tr><td>
-
-name
-
-
-</td><td>
-
-string
-
-
-</td><td>
-
-The name to give the logger.
-
-
-</td></tr>
-<tr><td>
-
-options
-
-
-</td><td>
-
-[LoggerOptions](./foundation-utils.loggeroptions.md)
-
-
-</td><td>
-
-_(Optional)_ The options to use when creating the logger.
-
-
-</td></tr>
-</tbody></table>
-
-**Returns:**
-
-[Logger](./foundation-utils.logger.md)
-
-The resulting logger.
-