diff --git a/docs/001_develop/03_client-capabilities/014_utility-methods/06_decorators-util.mdx b/docs/001_develop/03_client-capabilities/014_utility-methods/06_decorators-util.mdx new file mode 100644 index 0000000000..f25a9fce50 --- /dev/null +++ b/docs/001_develop/03_client-capabilities/014_utility-methods/06_decorators-util.mdx @@ -0,0 +1,95 @@ +--- +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 Genesis framework for web development. + +:::info +Decorator utilities are for projects using Genesis syntax only. +::: + +## Key Features + +- **Automatic Rerendering:** Automatically invokes the `render()` method of a component when any decorated property changes. +- **Integration with Genesis Framework:** Designed to work seamlessly with components extending `GenesisElement`. + +## 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, GenesisElement, html } from '@genesislcap/web-core'; + +@customElement({ + name: 'my-example-component', + template: html` + `, +}) +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. diff --git a/docs/001_develop/03_client-capabilities/014_utility-methods/07_error-util.mdx b/docs/001_develop/03_client-capabilities/014_utility-methods/07_error-util.mdx new file mode 100644 index 0000000000..84e328312b --- /dev/null +++ b/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` 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` 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.