From bc1fe51e5a49e8972d24e9de014b061b8d22e059 Mon Sep 17 00:00:00 2001
From: Gareth Spencer
 <25119104+Gareth-Spencer-Genesis@users.noreply.github.com>
Date: Mon, 2 Dec 2024 16:00:18 +0000
Subject: [PATCH 1/2] docs: mixins utilities PTL-1696

---
 .../014_utility-methods/08_mixins-util.mdx    | 77 +++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx

diff --git a/docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx b/docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx
new file mode 100644
index 000000000..54d3bd02c
--- /dev/null
+++ b/docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx
@@ -0,0 +1,77 @@
+---
+title: 'Mixins utilities'
+sidebar_label: 'Mixins utilities'
+id: mixins-util
+keywords: [utils, utility, mixins, augment, addition, lifecycle]
+tags:
+  - utils
+  - utility
+  - mixins
+  - augment
+  - addition
+  - lifecycle
+---
+
+The `mixins` category provides specialized functionalities that can be mixed into Genesis elements to enhance their capabilities and facilitate common patterns used within applications.
+
+:::info
+For Genesis code syntax only
+:::
+
+## 1. Lifecycle Mixin
+
+This mixin is designed to augment Genesis elements with additional control over their connect and disconnect lifecycle hooks. It's particularly useful for elements that are part of custom layouts or need to manage their lifecycle events in a granular manner.
+
+## Key Features
+
+- **Conditional Lifecycle Execution:** Offers methods to determine whether connect and disconnect lifecycle callbacks should run based on the element's current state and container.
+- **Layout Integration:** Seamlessly integrates with custom layouts by providing mechanisms to respect the dragging state and lifecycle update tokens.
+- **Cleanup Timeout:** Ensures elements removed from the layout are correctly cleaned up after a predefined timeout, avoiding memory leaks.
+
+## Examples
+
+#### `LifecycleMixin` Usage
+
+```typescript
+import { LifecycleMixin } from '@genesislcap/foundation-utils';
+import {customElement, GenesisElement, observable} from '@genesislcap/web-core';
+
+@customElement({
+  name: 'my-element',
+  template: html`<!-- template here -->`,
+})
+export class MyExampleComponent extends LifecycleMixin(GenesisElement) {
+  // Your element's implementation
+}
+```
+
+#### 2. Pending State Mixin
+
+This mixin introduces a pattern for managing elements that have asynchronous dependencies, such as data fetching or processing. It enables elements to signal their pending state and handle errors gracefully.
+
+#### Key Features
+
+- **Pending State Management:** Tracks pending asynchronous operations to provide feedback on the element's loading state.
+- **Progress Tracking:** Computes the progress of pending operations as a percentage, useful for loading indicators.
+- **Event Handling:** Raises custom events for state changes and errors, allowing parent components to react to the child's asynchronous state.
+
+#### `PendingState` Usage
+
+```typescript
+import { LifecycleMixin } from '@genesislcap/foundation-utils';
+import {customElement, GenesisElement, observable} from '@genesislcap/web-core';
+
+@customElement({
+  name: 'my-pending-element',
+  template: html`<!-- template here -->`,
+})
+export class MyExampleComponent extends PendingState(GenesisElement) {
+  // Element logic that involves asynchronous operations
+}
+```
+
+## Key Points
+
+- **Use Mixins Sparingly:** While mixins can offer powerful extensions to elements, they should be used judiciously to avoid complexity and maintain component clarity.
+- **Override With Care:** If overriding mixin methods or properties, ensure to call `super` to maintain the mixin's intended functionality.
+- **Document Mixin Behaviors:** Clearly document how mixins affect the behavior of your components, especially if they alter standard lifecycle behaviors or introduce new states and events.

From 1b85b6d8098c1e4869539bf846c708897f45a939 Mon Sep 17 00:00:00 2001
From: Gareth Spencer
 <25119104+Gareth-Spencer-Genesis@users.noreply.github.com>
Date: Tue, 3 Dec 2024 09:09:22 +0000
Subject: [PATCH 2/2] Update
 docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx

Co-authored-by: Matt Walker <43502076+matteematt@users.noreply.github.com>
---
 .../014_utility-methods/08_mixins-util.mdx                      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx b/docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx
index 54d3bd02c..3f29f29f2 100644
--- a/docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx
+++ b/docs/001_develop/03_client-capabilities/014_utility-methods/08_mixins-util.mdx
@@ -15,7 +15,7 @@ tags:
 The `mixins` category provides specialized functionalities that can be mixed into Genesis elements to enhance their capabilities and facilitate common patterns used within applications.
 
 :::info
-For Genesis code syntax only
+Mixins are used for projects using Genesis syntax only
 :::
 
 ## 1. Lifecycle Mixin