From 815e6b3300efdeb6f3d07ef00373faf9b7591673 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Szymon=20=C5=BBur?= Date: Mon, 2 Dec 2024 20:49:03 +0100 Subject: [PATCH 1/5] docs: decorators & error utilities PTL-1690 PTL-1692 --- .../06_decorators-util.mdx | 91 +++++++++++++++++ .../014_utility-methods/07_error-util.mdx | 99 +++++++++++++++++++ 2 files changed, 190 insertions(+) create mode 100644 docs/001_develop/03_client-capabilities/014_utility-methods/06_decorators-util.mdx create mode 100644 docs/001_develop/03_client-capabilities/014_utility-methods/07_error-util.mdx 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..801a0b7117 --- /dev/null +++ b/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` + `, +}) +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. From 1d5cb6fc94fa02f7e0f935c0f2f0cf7d4cefd2eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Szymon=20=C5=BBur?= Date: Tue, 3 Dec 2024 10:05:14 +0100 Subject: [PATCH 2/5] Update docs/001_develop/03_client-capabilities/014_utility-methods/06_decorators-util.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../014_utility-methods/06_decorators-util.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 801a0b7117..261a8c1735 100644 --- 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 @@ -32,7 +32,7 @@ tags: # 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. +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. ## Key Features From a72f7ca0e934ecd2a345f949e1cc2dc5077f1a9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Szymon=20=C5=BBur?= Date: Tue, 3 Dec 2024 10:05:28 +0100 Subject: [PATCH 3/5] Update docs/001_develop/03_client-capabilities/014_utility-methods/06_decorators-util.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../014_utility-methods/06_decorators-util.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 261a8c1735..e90de2b392 100644 --- 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 @@ -37,7 +37,7 @@ Provides utility decorators to enhance component behavior and development effici ## 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`. +- **Integration with Genesis Framework:** Designed to work seamlessly with components extending `GenesisElement`. ## Examples From 0736bee2133bc43bdfc4430ccfc96312517de5db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Szymon=20=C5=BBur?= Date: Tue, 3 Dec 2024 10:05:35 +0100 Subject: [PATCH 4/5] Update docs/001_develop/03_client-capabilities/014_utility-methods/06_decorators-util.mdx Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com> --- .../014_utility-methods/06_decorators-util.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index e90de2b392..a9b73cecc7 100644 --- 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 @@ -66,7 +66,7 @@ Suppose you have a component where you want certain attributes to trigger a rend ```typescript import { renderOnChange } from '@genesislcap/foundation-utils'; -import { attr, FASTElement, html } from '@genesislcap/web-core'; +import { attr, GenesisElement, html } from '@genesislcap/web-core'; @customElement({ name: 'my-example-component', From b7f3cf353eb02949b6d5fcde3be3a57e9c0e523e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Szymon=20=C5=BBur?= Date: Tue, 3 Dec 2024 10:09:27 +0100 Subject: [PATCH 5/5] Update 06_decorators-util.mdx --- .../014_utility-methods/06_decorators-util.mdx | 4 ++++ 1 file changed, 4 insertions(+) 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 index a9b73cecc7..f25a9fce50 100644 --- 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 @@ -34,6 +34,10 @@ tags: 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.