ueca-react 1.0.7 → 2.0.0

package/docs/Introduction to UECA-React.md

@@ -0,0 +1,24 @@
+# Introduction to UECA-React
+
+UECA-React is a framework designed to simplify the development of large-scale React applications by providing a unified and encapsulated component architecture. It encapsulates React and MobX behind a consistent component pattern, allowing developers to focus on high-level logic and structure rather than low-level implementation details.
+
+## Key Features
+- **Unified Component Structure**: All components follow a consistent pattern, reducing complexity and improving maintainability.
+- **Strong Typing**: Full TypeScript support ensures type safety and clarity.
+- **State Management**: Seamless integration with MobX for reactive state management.
+- **Property Bindings**: Powerful component property bindings for state synchronization.
+- **Event System**: Built-in support for events like `onChange<Property>` with safe handler invocation.
+- **Message Bus**: Lightweight messaging system for inter-component communication.
+- **Lifecycle Hooks**: Comprehensive set of hooks for fine-grained control over component lifecycle.
+- **Tracing Tools**: Enhanced trace log capabilities.
+- **Automated UI Testing Ready**: Automated UI testing tools can use component IDs as locators to identify and interact with UI elements.
+
+## Target Audience
+UECA-React is ideal for developers and teams working on large-scale React applications who are looking for a more structured and maintainable approach to building user interfaces. It is particularly beneficial for those who value type safety, consistency, and ease of debugging.
+
+## Why Choose UECA-React?
+- **Reduced Complexity**: Focus on business logic rather than React-specific boilerplate.
+- **Improved Maintainability**: Consistent component structure makes code easier to read, review, and test.
+- **Enhanced Productivity**: Simplified state management and event handling accelerate development.
+- **Scalability**: Designed to handle the demands of large-scale applications with ease.
+- **AI Code Generation**: UECA principles pave the way for AI-driven code generation. This documentation was created by a pretrained AI model.

package/docs/Lifecycle Hooks in UECA-React.md

@@ -0,0 +1,237 @@
+# Lifecycle Hooks in UECA-React
+#lifecycle #hooks #basics #api #example #best_practices
+
+## Description
+Lifecycle hooks in UECA-React provide a structured and predictable approach to managing a component’s behavior across its lifecycle stages. Unlike React’s `useEffect`, which relies on dependency arrays and can lead to complex logic, UECA-React offers a granular set of hooks that execute at specific points, such as model creation, DOM mounting, or UI rendering. Each hook receives the component’s `model`, enabling direct access to state, methods, and metadata, which is particularly powerful for dynamically created JSX content. This article details the lifecycle hooks, their sequence, chaining behavior, and centralized error handling.
+
+### Key Concepts
+- **Lifecycle Hooks**: Functions invoked at defined lifecycle stages.
+- **Granular Control**: Hooks for creation, initialization, mounting, rendering, and cleanup.
+- **Model Parameter**: Provides access to component properties, methods, and metadata (e.g., `fullId()`, `birthMark()`).
+- **Chaining**: Hooks and event handlers passed in JSX chain with those defined in the component’s model.
+- **Centralized Error Handling**: All errors (sync or async) are managed via `UECA.globalSettings.errorHandler`.
+
+## Overview of Lifecycle Hooks
+
+UECA-React provides the following hooks, each receiving the component’s `model`:
+
+1. **`constr(model)`**  
+   - **When**: Called once when the model is instantiated.  
+   - **Purpose**: One-time setup, like initializing non-reactive state or API clients.  
+   - **Example Use Case**: Fetching initial data.
+
+2. **`init(model)`**  
+   - **When**: Called after `constr()` on creation or cache retrieval.  
+   - **Purpose**: Initialization tasks for model activation, like resetting state.  
+   - **Example Use Case**: Subscribing to a WebSocket.
+
+3. **`mount(model)`**  
+   - **When**: Called when the component mounts to the DOM.  
+   - **Purpose**: DOM-related setup, like adding listeners.  
+   - **Example Use Case**: Attaching a resize listener.
+
+4. **`draw(model)`**  
+   - **When**: Called after view rendering.  
+   - **Purpose**: Post-render logic, similar to `useLayoutEffect`.  
+   - **Example Use Case**: Adjusting UI positions.
+
+5. **`erase(model)`**  
+   - **When**: Called before UI removal.  
+   - **Purpose**: Cleanup of UI resources before unmounting.  
+   - **Example Use Case**: Clearing animations.
+
+6. **`unmount(model)`**  
+   - **When**: Called when the component is removed from the DOM.  
+   - **Purpose**: DOM resource cleanup, like removing listeners.  
+   - **Example Use Case**: Detaching a resize listener.
+
+7. **`deinit(model)`**  
+   - **When**: Called when the component loses React context (e.g., cached but inactive).  
+   - **Purpose**: Cleanup of resources during deactivation.  
+   - **Example Use Case**: Unsubscribing from a WebSocket.
+
+**Note**: No `destr()` hook exists due to JavaScript garbage collection unpredictability; use `deinit()` for cleanup.
+
+## Sequence of Lifecycle Hooks
+Hooks execute in this order:
+1. `constr()` → Model creation.
+2. `init()` → Model activation.
+3. `mount()` → DOM attachment.
+4. `draw()` → UI rendering.
+5. `erase()` → UI removal preparation.
+6. `unmount()` → DOM detachment.
+7. `deinit()` → Model deactivation.
+
+## Model Parameter
+Each hook receives the component’s `model`, enabling access to properties (`model.count`), methods (`model.increment`), and metadata (`fullId()`, `birthMark()`). This is critical for **dynamic JSX**, where inline lifecycle hooks can customize behavior using `model`.
+
+## Centralized Error Handling
+All errors—synchronous or asynchronous—in hooks, methods, event handlers, or custom code are captured by `UECA.globalSettings.errorHandler`. This eliminates the need for try-catch blocks, streamlining error management.
+
+```typescript
+import * as UECA from "ueca-react";
+
+// Configure global error handler
+UECA.globalSettings.errorHandler = (error: Error) => {
+  console.error(`Error: ${error.message}`);
+  // Send a message to Message Bus to display the error dialog
+  UECA.defaultMessageBus<AppMessage>().unicast("App.UnhandledException", error);
+};
+```
+
+- **Sync Errors**: Caught automatically (e.g., invalid state in `init`).  
+- **Async Errors**: Handled from `async` hooks or methods without try-catch.
+
+## Chaining Hooks and Event Handlers
+Hooks and event handlers passed as `params` in JSX are **chained** with those defined in the component’s model hook. Chaining executes the model-defined handler first, followed by the JSX-passed handler, allowing layered logic.
+
+---
+
+## Code Examples
+
+### Example 1: Lifecycle Hooks with Centralized Error Handling
+A counter component logs lifecycle events and uses global error handling.
+
+```typescript
+import * as UECA from "ueca-react";
+
+type CounterStruct = UECA.ComponentStruct<{
+  props: { count: number };
+  methods: { increment: () => void };
+}>;
+
+type CounterParams = UECA.ComponentParams<CounterStruct>;
+type CounterModel = UECA.ComponentModel<CounterStruct>;
+
+function useCounter(params?: CounterParams): CounterModel {
+  const struct: CounterStruct = {
+    props: {
+      id: useCounter.name,
+      count: 0
+    },
+    constr: (model) => console.log(`constr: Model created: ${model.birthMark()}`),
+    init: async (model) => {
+      console.log(`init: Model initialized: ${model.fullId()}`);
+      // Simulate async error (handled by globalSettings.errorHandler)
+      if (Math.random() > 0.8) throw new Error("Init failed");
+      model.count = 0;
+    },
+    deinit: (model) => console.log(`deinit: Model deactivated: ${model.fullId()}`),
+    mount: (model) => console.log(`mount: Component mounted: ${model.fullId()}`),
+    unmount: (model) => console.log(`unmount: Component removed: ${model.fullId()}`),
+    draw: (model) => console.log(`draw: UI rendered: ${model.fullId()}`),
+    erase: (model) => console.log(`erase: UI about to be removed: ${model.fullId()}`),
+    methods: {
+      increment: () => model.count++,
+    },
+    View: () => (
+      <div id={model.htmlId()}>
+        <p>Counter: {model.count}</p>
+        <button onClick={model.increment}>Increment</button>
+      </div>
+    ),
+  };
+  const model = UECA.useComponent(struct, params);
+  return model;
+}
+
+const Counter = UECA.getFC(useCounter);
+export { CounterModel, useCounter, Counter };
+```
+
+- **Explanation**:  
+  - Hooks use `model` parameter to log `birthMark()` or `fullId()`.  
+  - `init` includes an async operation with potential errors, managed globally.  
+  - The component resets `count` and logs lifecycle stages.
+
+### Example 2: Dynamic JSX with Chained Hooks
+This example shows a dynamically created `Counter` with chained lifecycle hooks.
+
+```typescript
+import * as UECA from "ueca-react";
+
+type AppStruct = UECA.ComponentStruct<{
+  props: { showCounter: boolean };
+}>;
+
+function useApp(): UECA.ComponentModel<AppStruct> {
+  const struct: AppStruct = {
+    props: { 
+      id: useApp.name,
+      showCounter: true;
+    },
+    View: () => (
+      <div id={model.htmlId()}>
+        <button onClick={() => (model.showCounter = !model.showCounter)}>
+          Toggle Counter
+        </button>
+        {model.showCounter && (
+          <Counter
+            id={"counter1"}
+            constr={(counter_model) => console.log(`JSX constr: ${counter_model.birthMark()}`)}
+            init={(counter_model) => {
+              console.log(`JSX init: ${counter_model.fullId()}`);
+              counter_model.count = 10;
+            }}
+            onChangeCount={(newValue) => console.log(`JSX count changed: ${newValue}`)}
+          />
+        )}
+      </div>
+    ),
+  };
+  const model = UECA.useComponent(struct, params);
+  return model;
+}
+
+const App = UECA.getFC(useApp);
+export { App };
+```
+
+- **Explanation**:  
+  - The `Counter` is instantiated dynamically in JSX with inline `constr`, `init`, and `onChangeCount`.  
+  - Model-defined hooks (e.g., `init` in `useCounter`) execute first, followed by JSX-passed hooks, chaining their logic.  
+  - The `onChangeCount` event handler in JSX chains with any model-defined handler, logging count changes.  
+  - Errors in inline hooks are caught by `globalSettings.errorHandler`.
+
+---
+
+## Best Practices
+- **Use `constr` for One-Time Setup**: Initialize static resources like API clients.  
+- **Leverage `init` and `deinit` for Activation**: Manage subscriptions or state resets.  
+- **Keep `mount` and `unmount` DOM-Specific**: Focus on DOM interactions.  
+- **Optimize `draw` and `erase` for UI**: Handle render-related tasks.  
+- **Use Global Error Handling**: Rely on `globalSettings.errorHandler` for all errors.  
+- **Chain Hooks Judiciously**: Ensure JSX-passed hooks complement model-defined ones without redundancy.
+
+---
+
+## Comparison to Traditional React
+React’s `useEffect` requires dependency arrays, often leading to stale closures or complex cleanup. UECA-React hooks:
+- **Eliminate Dependencies**: Fixed execution order simplifies logic.  
+- **Clarify Intent**: Named hooks are self-explanatory.  
+- **Enable Chaining**: JSX-passed hooks extend model-defined logic.  
+- **Streamline Errors**: Centralized handling reduces boilerplate.
+
+Example in React:
+```typescript
+useEffect(() => {
+  console.log("Mounted");
+  return () => console.log("Unmounted");
+}, []);
+```
+
+In UECA-React:
+```typescript
+mount: (model) => console.log(`Mounted: ${model.fullId()}`),
+unmount: (model) => console.log(`Unmounted: ${model.fullId()}`),
+```
+
+---
+
+## Notes
+- Hooks are optional; omit unused ones for efficiency.  
+- Asynchronous hooks support tasks like API calls, with errors managed globally.  
+- The `model` parameter enables dynamic JSX customization, accessing model state, methods, etc.
+- Chaining applies to both hooks and event handlers, executing model-defined logic first.  
+- When using model caching (version 2.0), `init` and `deinit` manage cache cycles.  
+- Test chained hooks/handlers to ensure combined logic behaves as expected.

package/docs/Message Bus in UECA-React.md

@@ -0,0 +1,260 @@
+# Message Bus in UECA-React
+#message_bus #communication #events #decouple
+
+## Description
+The UECA Message Bus is a centralized communication system in UECA-React that enables decoupled interaction between components. It allows components to post messages to a bus and subscribe to specific message types, promoting a modular and scalable architecture. By using the message bus, components can communicate without direct dependencies, making the application easier to maintain and extend.
+
+---
+
+## API/Methods
+
+### Message Type Declaration
+#message_type
+
+To use the message bus, you must first define the message types that your application will use. Message types are declared as a TypeScript type, specifying the input (`in`) and output (`out`) for each message. This ensures type safety when posting and handling messages.
+
+   ```typescript
+   type AppMessage = {
+     "GetCurrentTime": {     
+       out: { time: string };
+     };
+     "Api.GetWeatherForecast": {
+       in: { zip_code: string };
+       out: { temperature: number; rainProbability: number };
+     };
+   };
+   ```
+- Each message type (e.g., `Api.GetWeatherForecast`) defines:
+  - `in`: The input parameters (optional).
+  - `out`: The expected output (optional).
+
+
+### Posting a Message
+#post #broadcast #unicast
+
+- **model.bus.broadcast(modelIdFilter, messageType, payload)**  
+  Posts a message to the bus for subscribers matching `modelIdFilter` with the specified `messageType` and optional `payload`. This method sends a message to be handled by all subscribers whose `model.fullId()` matches the `modelIdFilter` condition.  
+  - **Parameters**:  
+    - `modelIdFilter`: A string or RegExp identifying subscriber `model.fullId()` (e.g., `app.ui.screen.nameInput`, `^app\.ui\.screen\.editor\.[a-zA-Z0-9_]+Input$`). Use `undefined`, `null`, or `""` to target all subscribers.
+    - `messageType`: A string identifying the message type (e.g., `"UI.Screen.DisableControls"`).  
+    - `payload`: An optional object containing data sent with the message.  
+  - **Returns**: A Promise that resolves with an array of responses from all message handlers (if any). 
+
+- **model.bus.unicast(messageType, payload)**
+  Posts a message to the bus with the specified `messageType` and optional `payload`. This method sends a message to be handled by one subscriber. Note: if multiple subscribers listen for the same message, only the first subscriber will receive it.
+  - **Parameters**:  
+    - `messageType`: A string identifying the type of message (e.g., `Api.GetWeatherForecast`).  
+    - `payload`: An optional object containing data to be sent with the message.  
+  - **Returns**: A promise that resolves with the response from the message handler (if any).
+
+- **model.bus.castTo(modelId, messageType, payload)**  
+  Posts a message to the bus for the subscriber matching `modelId` with the specified `messageType` and optional `payload`. This method sends a message to be handled by one subscriber whose `model.fullId()` is `modelId`.
+  - **Parameters**:
+    - `modelId`: A string identifying subscriber `model.fullId()` (e.g., `app.ui.screen.nameInput`).  
+    - `messageType`: A string identifying the message type (e.g., `"UI.Screen.ResetControls"`).
+    - `payload`: An optional object containing data sent with the message.  
+  - **Returns**: A promise that resolves with the response from the message handler (if any).
+
+
+### Subscribing to Messages
+- **messages**  
+  A section within the component structure where handlers for specific message types are defined. Each handler is a function that processes the message and can return a response.  
+  - **Format**: An object where keys are message types and values are handler functions.  
+  - **Handler Signature**: `(payload) => response`, where `payload` is the input data and `response` is a promise wih the output (if applicable).
+
+---
+
+## Registering Message Bus Events
+#handlers #subscription
+
+To handle specific message types (i.e., register message bus events), a component must define handlers in its structure. This is done by including a `messages` object within the component's `struct`, where each key is a message type and the value is a handler function that processes the message.
+
+### Steps to Register Message Bus Events
+1. **Include Message Type in Component Structure**:  
+   Pass the message type (e.g., `AppMessage`) as the second type parameter to `UECA.ComponentStruct` when defining the component's structure. This ensures type safety for both message handlers and message posting.
+
+   ```typescript   
+   type ServiceStruct = UECA.ComponentStruct<{}, AppMessage>;
+   ```
+
+2. **Define Handlers in `messages`**:  
+   Within the `struct`, add the `messages` object and specify handlers for the message types you want to handle. Each handler must match the `in` and `out` types defined in `AppMessage`.
+
+   ```typescript
+   const struct: ServiceStruct = {
+     messages: {
+       "GetCurrentTime": async () => {
+         return { time: new Date().toLocaleTimeString() };
+       },
+     },
+   };
+   ```
+
+### Key Points
+- **Type Safety**: Including the message type in `UECA.ComponentStruct` ensures that handler functions align with the defined message types.
+- **Automatic Subscription**: The framework automatically subscribes the component to the message types listed in `messages`; no additional subscription code is required.
+- **Async Handlers**: Handlers are asynchronous returning a promise that resolves with the response.
+
+---
+
+## Passing the Message Type to `UECA.ComponentStruct`
+#generic_type #typescript
+
+The `UECA.ComponentStruct` generic type is used to define the structure of a component, including its props, events, children, methods, and message handlers. To enable a component to interact with the message bus (either by posting or handling messages), you must pass the application’s message type (e.g., `AppMessage`) as the second type parameter.
+
+### Syntax
+```typescript
+type ComponentStruct = UECA.ComponentStruct<ComponentStructure, MessageType>;
+```
+- `ComponentStructure`: The first type parameter defines the component’s structure (e.g., props, events, children, methods).
+- `MessageType`: The second type parameter specifies the message type (e.g., `AppMessage`), ensuring type safety for message-related operations.
+
+### Why It’s Required
+- **For Handlers**: Ensures the `messages` object’s handlers match the input and output types in `AppMessage`.
+- **For Posting**: Allows the bus methods (e.g. `model.bus.unicast`) to enforce correct message types and payloads when sending messages.
+
+### Example Usage
+For a component that handles messages:
+```typescript
+type TimeServiceStruct = UECA.ComponentStruct<{}, AppMessage>;
+```
+
+For a component that posts messages:
+```typescript
+type TimeDisplayStruct = UECA.ComponentStruct<{
+  props: { currentTime: string };
+  methods: { updateTime: () => void };
+}, AppMessage>;
+```
+
+---
+
+## Posting Messages
+#posting #unicast
+
+To post a message, use the `model.bus.unicast` method (or `model.bus.broadcast`, `model.bus.castTo`), which sends a message to the bus and returns a promise with the handler’s response.
+
+### Example: Posting a Message
+```typescript
+async function updateTime() {
+  const response = await model.bus.unicast("GetCurrentTime");
+  model.currentTime = response.time;
+}
+```
+
+- **Parameters**:  
+  - `messageType`: The type of message (e.g., `"GetCurrentTime"`).  
+  - `payload`: Optional data matching the `in` type (not needed here since `in` is not requred).  
+- **Returns**: A promise resolving to the handler’s response (e.g., `{ time: string }`).
+
+---
+
+## Example: Weather Application
+#example #tutorial
+
+This example demonstrates how to register message bus events and pass the message type to `UECA.ComponentStruct` in a weather application with two components: one that handles weather data requests and one that posts them.
+
+### Message Type
+```typescript
+type AppMessage = {
+  "Api.GetWeatherForecast": {
+    in: { zip_code: string };
+    out: { temperature: number; rainProbability: number };
+  };
+};
+```
+
+### WeatherService Component (Handler)
+```typescript
+type WeatherServiceStruct = UECA.ComponentStruct<{}, AppMessage>;
+
+function useWeatherService(): UECA.ComponentModel<WeatherServiceStruct> {
+  const struct: WeatherServiceStruct = {
+    messages: {
+      "Api.GetWeatherForecast": async ({ zip_code }) => {
+        const response = await fetch(`https://api.weather.com/v3/wx/forecast/daily/5day?postalKey=${zip_code}&format=json`);
+        const data = await response.json();
+        return { temperature: data.temperature, rainProbability: data.rainProbability };    
+      },
+    },
+  };
+  return UECA.useComponent(struct);
+}
+
+const WeatherService = UECA.getFC(useWeatherService);
+```
+
+### WeatherForm Component (Poster)
+```typescript
+type WeatherFormStruct = UECA.ComponentStruct<{
+  props: { 
+    zip_code: string;
+    weatherData: { 
+      temperature: number;
+      rainProbability: number 
+    }
+  };
+  methods: { 
+    submitForm: () => void
+  };
+}, AppMessage>;
+
+function useWeatherForm(): UECA.ComponentModel<WeatherFormStruct> {
+  const struct: WeatherFormStruct = {
+    props: {
+      zip_code: "",
+      weatherData: undefined
+    },
+    methods: {
+      submitForm: async () => {
+        model.weatherData = await model.bus.unicast("Api.GetWeatherForecast", {zip_code: model.zip_code });
+      },
+    },
+    View: () => (
+      <div id={model.htmlId()}>
+        <input value={model.zip_code} onChange={(e) => model.zip_code = e.target.value} placeholder="Zip Code" />        
+        <button onClick={model.submitForm}>Get Weather</button>
+        {model.weatherData && (
+          <p>Temperature: {model.weatherData.temperature}°C, Rain Probability: {model.weatherData.rainProbability}%</p>
+        )}
+      </div>
+    ),
+  };
+  return UECA.useComponent(struct);
+}
+
+const WeatherForm = UECA.getFC(useWeatherForm);
+```
+
+### Integrating in the App
+```typescript
+function App() {
+  return (
+    <div>
+      <WeatherForm />
+      <WeatherService />
+    </div>
+  );
+}
+```
+
+**Explanation**:
+- **Message Type**: `AppMessage` defines `"Api.GetWeatherForecast"` with input (`zip_code`) and output (`temperature`, `rainProbability`).
+- **Handler Registration**: `WeatherService` registers a handler for `"Api.GetWeatherForecast"` in its `messages` object.
+- **Type Passing**: Both components pass `AppMessage` to `UECA.ComponentStruct` for type safety.
+- **Posting**: `WeatherForm` uses `model.bus.unicast` to request weather data, updating its display with the response.
+
+---
+
+## Best Practices
+- **Use Clear Message Names**: Choose descriptive names (e.g., `"Api.GetWeatherForecast"`) to indicate purpose.
+- **Handle Errors**: Implement error handling in asynchronous handlers or configure the global error handler `globalSettings.errorHandler` to handle all application errors in one place (e.g. write to the log, pop up a message, etc.).
+- **Keep Payloads Minimal**: Only include necessary data in the message payload.
+- **Centralize Message Types**: Define all message types in a single file for consistency.
+
+---
+
+## Notes
+- The message bus routes messages to the handler registered for the message type.
+- Only one component should handle a specific message type to avoid conflicts (unless it's a broadcast message).
+- Components interacting with the message bus (posting or handling) must include the message type in their structure.

package/docs/Model Caching in UECA-React.md

@@ -0,0 +1,144 @@
+# Model Caching in UECA-React
+#model_caching #state #reactivity #performance
+
+## Description
+Model caching in UECA-React is a powerful feature introduced in version 2.0 that enables components to persist their state across mounts and unmounts. By caching component models, UECA-React ensures that state is preserved when components are temporarily removed from the DOM (e.g., due to conditional rendering) and restored when they reappear. This enhances performance and improves user experience by maintaining state continuity without requiring manual state management.
+
+Key aspects of model caching:
+- **State Persistence**: Retains model state (e.g., form inputs, counters) during unmount/mount cycles.
+- **Configurable Modes**: Supports `no-cache`, `cache`, and `auto-cache` modes via `UECA.globalSettings.modelCacheMode`.
+- **Type-Safe**: Fully integrated with UECA’s TypeScript-based architecture.
+- **Reactive**: Works seamlessly with MobX-driven reactivity.
+
+---
+
+## API/Methods
+
+### Configuring Model Caching
+- **UECA.globalSettings.modelCacheMode**  
+  Sets the global caching mode for all component models.  
+  - **Values**:  
+    - `"no-cache"`: Disables caching; models are recreated on each mount.  
+    - `"cache"`: Caches models only if their `cacheable` property is explicitly set to `true`.  
+    - `"auto-cache"`: Automatically caches models unless `cacheable` is explicitly set to `false`.  
+  - **Default**: `"auto-cache"`.
+
+### Model Properties
+- **cacheable**  
+  A property in the component’s `props` that controls whether the model is cached.  
+  - **Type**: `boolean | undefined`  
+  - **Behavior**:  
+    - `true`: Model is cached (in `"cache"` mode).  
+    - `false`: Model is not cached (in `"auto-cache"` mode).  
+    - `undefined`: Follows the global `modelCacheMode` (cached in `"auto-cache"`).
+
+### Lifecycle Hooks
+- **init()**: Called when a model is activated, either on creation or when retrieved from cache.  
+- **deinit()**: Called when a model is deactivated, typically when it’s cached but no longer in use.
+
+---
+
+## Code Examples
+
+### Example: Caching a Counter Component
+This example demonstrates model caching with a `Counter` component that persists its state across mounts and a `Display` component that toggles its visibility.
+
+```typescript
+import * as UECA from "ueca-react";
+
+// Enable auto-caching globally
+UECA.globalSettings.modelCacheMode = "auto-cache";
+
+type CounterStruct = UECA.ComponentStruct<{
+    props: {
+        count: number;
+    }    
+}>;
+
+type CounterParams = UECA.ComponentParams<CounterStruct>;
+type CounterModel = UECA.ComponentModel<CounterStruct>;
+
+function useCounter(params?: CounterParams): CounterModel {
+    const struct: CounterStruct = {
+        props: {
+            id: useCounter.name,
+            count: 0
+        },        
+        init: () => {
+            console.log("Model activated with count:", model.count);
+        },
+        deinit: () => {
+            console.log("Model deactivated");
+        },
+        View: () => (
+            <div id={model.htmlId()}>
+                <p>Count: {model.count}</p>
+                <button onClick={() => model.count++}>Increment</button>
+            </div>
+        )
+    };
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+
+type DisplayStruct = UECA.ComponentStruct<{    
+    children: {
+        staticCounter: CounterModel;
+        dynamicCounter: CounterModel; // Optional declaration for dynamic access
+    };    
+}>;
+
+type DisplayStructParams = UECA.ComponentParams<DisplayStruct>;
+type DisplayStructModel = UECA.ComponentModel<DisplayStruct>;
+
+function useDisplay(params?: DisplayStructParams): DisplayStructModel {
+    const struct: DisplayStruct = {
+        props: {
+            id: useDisplay.name            
+        },
+        children: {            
+            staticCounter: useCounter({ 
+                onChangeCount: () => console.log(`Static Counter changed to: ${model.staticCounter.count}`)
+            })
+        },
+        View: () => (
+            <div id={model.htmlId()}>                
+                {/* Static child */}
+                <model.staticCounter.View />
+                {/* Dynamic child */}
+                <Counter id={"dynamicCounter"}
+                    onChangeCount={() => console.log(`Dynamic Counter changed to: ${model.dynamicCounter.count}`)}
+                />
+            </div>
+        )
+    };
+    const model = UECA.useComponent(struct, params);
+    return model;
+}
+
+const Counter = UECA.getFC(useCounter);
+const Display = UECA.getFC(useDisplay);
+
+export { CounterModel, useCounter, Counter, useDisplay, Display };
+```
+
+- **Explanation**:  
+  - **Global Configuration**: `UECA.globalSettings.modelCacheMode = "auto-cache"` enables caching for models unless `cacheable` is explicitly `false`.  
+  - **Counter Component**: The `Counter` component persists its `count` state across mounts/unmounts due to caching. The `init` and `deinit` hooks log model activation/deactivation.  
+  - **Display Component**: The `staticCounter` is a cached child model, and `dynamicCounter` is a dynamically instantiated component. Both maintain state when toggled in/out of the DOM.  
+  - **Behavior**: Incrementing the counter and toggling visibility (e.g., via conditional rendering) preserves the `count` value, demonstrating state continuity.
+
+---
+
+## Best Practices
+- **Choose the Right Mode**: Use `"auto-cache"` for most applications to balance performance and simplicity. Reserve `"cache"` for explicit control or `"no-cache"` for version 1.0 behavior.  
+- **Set `cacheable` Explicitly**: When needed, define `cacheable` in `props` to override the global mode (e.g., `cacheable: false` for transient components).  
+- **Optimize `init` and `deinit`**: Use these hooks for setup/cleanup tasks (e.g., subscriptions) to manage resources efficiently during caching cycles.  
+- **Monitor Performance**: Avoid caching large models unnecessarily to prevent memory overhead.
+
+---
+
+## Notes
+- Model caching is enabled by default in version 2.0 with `"auto-cache"`, but it requires careful configuration for optimal memory usage.  
+- The `id` property (e.g., `id={"dynamicCounter"}`) is critical for cache identification, ensuring models are correctly restored.  
+- Caching integrates with UECA’s reactivity, preserving state changes made via MobX observables.