docs: decorators & error utilities PTL-1690 PTL-1692

docs/001_develop/03_client-capabilities/014_utility-methods/06_decorators-util.mdx

@@ -0,0 +1,91 @@
+---
+title: 'Decorators Utilities'
+sidebar_label: 'Decorators Utilities'
+id: decorators-utils
+keywords: [utils, utility, data, decorators, env, environment, formatters, number, date, logger, logging, mappers, mixins, observers, resource, server, serializer, json, styles, css, UUID, unique, window, iframe]
+tags:
+  - utils
+  - utility
+  - data
+  - decorators
+  - env
+  - environment
+  - formatters
+  - number
+  - date
+  - logger
+  - logging
+  - mappers
+  - mixins
+  - observers
+  - resource
+  - server
+  - serializer
+  - json
+  - styles
+  - css
+  - UUID
+  - unique
+  - window
+  - iframe
+---
+
+# Decorators utilities
+
+Provides utility decorators to enhance component behavior and development efficiency within TypeScript projects. Specifically, the `renderOnChange` decorator automates the re-rendering process of components upon property changes, leveraging the FAST framework for web development.
+
+## Key Features
+
+- **Automatic Rerendering:** Automatically invokes the `render()` method of a component when any decorated property changes.
+- **Integration with FAST Framework:** Designed to work seamlessly with components extending `FASTElement`.
+
+## Examples
+
+### Using `renderOnChange`
+
+Apply the `renderOnChange` decorator to properties that should trigger a re-render upon change:
+
+```typescript
+import { renderOnChange } from '@genesislcap/foundation-utils';
+import { GenesisElement, attr } from '@genesislcap/web-core';
+
+export class MyExampleComponent extends GenesisElement {
+  @attr({ mode: 'boolean', attribute: 'line-numbers' })
+  @renderOnChange
+  lineNumbers: boolean = true;
+
+  @attr
+  @renderOnChange
+  indent: number | 'tab' = 2;
+}
+```
+
+### Using with template
+
+Suppose you have a component where you want certain attributes to trigger a render when they change, such as a custom input element where the `value` and `placeholder` properties are observed:
+
+```typescript
+import { renderOnChange } from '@genesislcap/foundation-utils';
+import { attr, FASTElement, html } from '@genesislcap/web-core';
+
+@customElement({
+  name: 'my-example-component',
+  template: html`
+    <input type="text" placeholder="${x => x.placeholder}" value="${x => x.value}" />`,
+})
+export class MyExampleComponent extends GenesisElement {
+  @attr
+  @renderOnChange
+  value: string = '';
+
+  @attr
+  @renderOnChange
+  placeholder: string = 'Enter text...';
+}
+```
+
+In this example, changes to either `value` or `placeholder` will automatically invoke the `render()` method, ensuring the component's visual state is immediately updated to reflect these changes.
+
+## Considerations
+
+When using `renderOnChange`, consider the performance implications of frequent re-rendering, especially for components with complex rendering logic or those nested within deep component trees. Optimize your `render()` method to be as efficient as possible and minimize unnecessary DOM updates.

docs/001_develop/03_client-capabilities/014_utility-methods/07_error-util.mdx

@@ -0,0 +1,99 @@
+---
+title: 'Error Utilities'
+sidebar_label: 'Error Utilities'
+id: error-utils
+keywords: [utils, utility, data, decorators, env, environment, formatters, number, date, logger, logging, mappers, mixins, observers, resource, server, serializer, json, styles, css, UUID, unique, window, iframe]
+tags:
+  - utils
+  - utility
+  - data
+  - decorators
+  - env
+  - environment
+  - formatters
+  - number
+  - date
+  - logger
+  - logging
+  - mappers
+  - mixins
+  - observers
+  - resource
+  - server
+  - serializer
+  - json
+  - styles
+  - css
+  - UUID
+  - unique
+  - window
+  - iframe
+---
+
+# Error Utilities
+
+Provides a sophisticated system for managing errors within your application. By leveraging TypeScript interfaces and types, it provides a structured approach to recording, accessing, and logging errors.
+
+## Key Features
+
+- **`ErrorMap<TErrorDetailMap>` Interface:** Outlines the structure for an error map, including methods for setting, getting, and managing errors, alongside properties for accessing the last error and a consolidated error message string.
+- **`DefaultErrorMap<TErrorDetailMap>` Class:** Implements the `ErrorMap` interface, providing concrete logic for error management, including observable properties for reactive UI updates.
+
+## Examples
+
+### Creating an Error Map
+
+Use the `createErrorMap` factory function to instantiate an `ErrorMap` with a custom logger function. This logger is invoked whenever an error is set, allowing for flexible error reporting.
+
+```typescript
+import { createErrorMap } from '@genesislcap/foundation-utils';
+
+const logger = (key, error) => console.error(`Error [${key}]:`, error.message);
+const errorMap = createErrorMap(logger);
+```
+
+### Recording an Error
+
+Add errors to the map using the `set` method. This records the error under the specified key and updates the `lastError` observable property.
+
+```typescript
+errorMap.set('networkError', new Error('Failed to fetch data'));
+```
+
+### Accessing Errors
+
+Retrieve specific errors by key, check for their presence, or get all errors as an iterable collection using `get`, `has`, and `values` methods, respectively.
+
+```typescript
+if (errorMap.has('networkError')) {
+  const networkError = errorMap.get('networkError');
+  console.log(networkError.message);
+}
+
+for (const error of errorMap.values()) {
+  console.warn(error.message);
+}
+```
+
+### Managing Errors
+
+Errors can be individually removed or the entire map can be cleared. The `lastError` is also managed accordingly.
+
+```typescript
+errorMap.delete('networkError'); // Remove a specific error
+errorMap.clear(); // Clear all errors
+```
+
+### Error Messages
+
+The `messages` property provides a concatenated string of all error messages, prefaced by the total error count. This is useful for displaying error summaries to the user.
+
+```typescript
+console.log(errorMap.messages); // Outputs formatted error messages
+```
+
+## Considerations
+
+- Utilize the `ErrorMap` to centralize error handling and reporting in your application.
+- Leverage the `lastError` and `messages` for user-facing error feedback, ensuring a comprehensive overview of current issues.
+- Employ the provided logger function to integrate with existing logging frameworks or error tracking services, enhancing observability.